Skip to content

Commit cf25af7

Browse files
kateinoigakukunkateinoigakukun
committed
Documentation: Add Package output structure article
1 parent 15b2a0d commit cf25af7

File tree

2 files changed

+156
-0
lines changed

2 files changed

+156
-0
lines changed

‎Sources/JavaScriptKit/Documentation.docc/Articles/Package-Output-Structure.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Package Output Structure
2+
3+
Understand the structure and contents of the JavaScript package generated by the `swift package js` command.
4+
5+
## Overview
6+
7+
When you run `swift package --swift-sdk $SWIFT_SDK_ID js`, the PackageToJS plugin compiles your Swift code to WebAssembly and generates a JavaScript package in `.build/plugins/PackageToJS/outputs/Package/`. This package contains all the necessary files to run your Swift application in JavaScript environments (browser or Node.js).
8+
9+
## Package Structure
10+
11+
The output package has the following structure:
12+
13+
```
14+
.build/plugins/PackageToJS/outputs/Package/
15+
├── ProductName.wasm # Compiled WebAssembly module
16+
├── index.js # Main entry point for browser environments
17+
├── index.d.ts # TypeScript type definitions for index.js
18+
├── instantiate.js # Low-level instantiation API
19+
├── instantiate.d.ts # TypeScript type definitions for instantiate.js
20+
├── package.json # npm package metadata
21+
└── platforms/
22+
├── browser.js # Browser-specific platform setup
23+
├── browser.d.ts # TypeScript definitions for browser.js
24+
├── node.js # Node.js-specific platform setup
25+
└── node.d.ts # TypeScript definitions for node.js
26+
```
27+
28+
## Using the Package
29+
30+
### In Browser
31+
32+
```html
33+
<!DOCTYPE html>
34+
<html>
35+
<body>
36+
<script type="module">
37+
import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';
38+
await init();
39+
</script>
40+
</body>
41+
</html>
42+
```
43+
44+
### In Node.js
45+
46+
```javascript
47+
import { instantiate } from './.build/plugins/PackageToJS/outputs/Package/instantiate.js';
48+
import { defaultNodeSetup } from './.build/plugins/PackageToJS/outputs/Package/platforms/node.js';
49+
50+
async function main() {
51+
const options = await defaultNodeSetup();
52+
await instantiate(options);
53+
}
54+
55+
main();
56+
```
57+
58+
> Tip: For a complete Node.js setup example, see the [NodeJS example](https://github.com/swiftwasm/JavaScriptKit/tree/main/Examples/NodeJS).
59+
60+
### With Bundlers (Vite, Webpack, etc.)
61+
62+
The generated package can be consumed by JavaScript bundlers:
63+
64+
```bash
65+
npm install .build/plugins/PackageToJS/outputs/Package
66+
```
67+
68+
Then import it in your JavaScript code:
69+
70+
```javascript
71+
import { init } from 'package-name';
72+
await init();
73+
```
74+
75+
## Core Files
76+
77+
### WebAssembly Module (`ProductName.wasm`)
78+
79+
The compiled WebAssembly binary containing your Swift code. The filename matches your SwiftPM product name (e.g., `Basic.wasm` for a product named "Basic").
80+
81+
### Entry Point (`index.js`)
82+
83+
The main entry point for browser environments. It provides a convenient `init()` function that handles module instantiation with default settings.
84+
85+
```javascript
86+
import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';
87+
88+
// Initialize with default browser setup
89+
await init();
90+
```
91+
92+
For packages with BridgeJS imports, you can provide custom imports:
93+
94+
```javascript
95+
import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';
96+
97+
await init({
98+
getImports: () => ({
99+
// Your custom imports
100+
})
101+
});
102+
```
103+
104+
### Instantiation API (`instantiate.js`)
105+
106+
A lower-level API for more control over module instantiation. Use this when you need to customize the WebAssembly instantiation process or WASI setup.
107+
108+
```javascript
109+
import { instantiate } from './.build/plugins/PackageToJS/outputs/Package/instantiate.js';
110+
import { defaultBrowserSetup } from './.build/plugins/PackageToJS/outputs/Package/platforms/browser.js';
111+
112+
const options = await defaultBrowserSetup({
113+
module: fetch('./ProductName.wasm'),
114+
// ... other options
115+
});
116+
117+
const { instance, swift, exports } = await instantiate(options);
118+
```
119+
120+
### Platform-Specific Setup
121+
122+
The `platforms/` directory contains platform-specific setup functions:
123+
- `platforms/browser.js` - Provides `defaultBrowserSetup()` for browser environments
124+
- `platforms/node.js` - Provides `defaultNodeSetup()` for Node.js environments
125+
126+
## Package Metadata (`package.json`)
127+
128+
The generated `package.json` includes:
129+
130+
```json
131+
{
132+
"name": "package-name",
133+
"version": "0.0.0",
134+
"type": "module",
135+
"private": true,
136+
"exports": {
137+
".": "./index.js",
138+
"./wasm": "./ProductName.wasm"
139+
},
140+
"dependencies": {
141+
"@bjorn3/browser_wasi_shim": "0.3.0"
142+
}
143+
}
144+
```
145+
146+
The `exports` field allows importing the package as an npm dependency:
147+
148+
```javascript
149+
import { init } from '.build/plugins/PackageToJS/outputs/Package';
150+
```
151+
152+
## TypeScript Support
153+
154+
All JavaScript files have corresponding `.d.ts` TypeScript definition files, providing full type safety when using the package in TypeScript projects.
155+

‎Sources/JavaScriptKit/Documentation.docc/Documentation.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Check out the [examples](https://github.com/swiftwasm/JavaScriptKit/tree/main/Ex
5151

5252
### Articles
5353

54+
- <doc:Package-Output-Structure>
5455
- <doc:Deploying-Pages>
5556
- <doc:JavaScript-Environment-Requirements>
5657
- <doc:Testing>

0 commit comments

Comments
 (0)