Skip to content

Commit fe6f380

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

File tree

2 files changed

+154
-0
lines changed

2 files changed

+154
-0
lines changed

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

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
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+
### With Bundlers (Vite, Webpack, etc.)
59+
60+
The generated package can be consumed by JavaScript bundlers:
61+
62+
```bash
63+
npm install .build/plugins/PackageToJS/outputs/Package
64+
```
65+
66+
Then import it in your JavaScript code:
67+
68+
```javascript
69+
import { init } from 'package-name';
70+
await init();
71+
```
72+
73+
## Core Files
74+
75+
### WebAssembly Module (`ProductName.wasm`)
76+
77+
The compiled WebAssembly binary containing your Swift code. The filename matches your SwiftPM product name (e.g., `Basic.wasm` for a product named "Basic").
78+
79+
### Entry Point (`index.js`)
80+
81+
The main entry point for browser environments. It provides a convenient `init()` function that handles module instantiation with default settings.
82+
83+
```javascript
84+
import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';
85+
86+
// Initialize with default browser setup
87+
await init();
88+
```
89+
90+
For packages with BridgeJS imports, you can provide custom imports:
91+
92+
```javascript
93+
import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';
94+
95+
await init({
96+
getImports: () => ({
97+
// Your custom imports
98+
})
99+
});
100+
```
101+
102+
### Instantiation API (`instantiate.js`)
103+
104+
A lower-level API for more control over module instantiation. Use this when you need to customize the WebAssembly instantiation process or WASI setup.
105+
106+
```javascript
107+
import { instantiate } from './.build/plugins/PackageToJS/outputs/Package/instantiate.js';
108+
import { defaultBrowserSetup } from './.build/plugins/PackageToJS/outputs/Package/platforms/browser.js';
109+
110+
const options = await defaultBrowserSetup({
111+
module: fetch('./ProductName.wasm'),
112+
// ... other options
113+
});
114+
115+
const { instance, swift, exports } = await instantiate(options);
116+
```
117+
118+
### Platform-Specific Setup
119+
120+
The `platforms/` directory contains platform-specific setup functions:
121+
- `platforms/browser.js` - Provides `defaultBrowserSetup()` for browser environments
122+
- `platforms/node.js` - Provides `defaultNodeSetup()` for Node.js environments
123+
124+
## Package Metadata (`package.json`)
125+
126+
The generated `package.json` includes:
127+
128+
```json
129+
{
130+
"name": "package-name",
131+
"version": "0.0.0",
132+
"type": "module",
133+
"private": true,
134+
"exports": {
135+
".": "./index.js",
136+
"./wasm": "./ProductName.wasm"
137+
},
138+
"dependencies": {
139+
"@bjorn3/browser_wasi_shim": "0.3.0"
140+
}
141+
}
142+
```
143+
144+
The `exports` field allows importing the package as an npm dependency:
145+
146+
```javascript
147+
import { init } from '.build/plugins/PackageToJS/outputs/Package';
148+
```
149+
150+
## TypeScript Support
151+
152+
All JavaScript files have corresponding `.d.ts` TypeScript definition files, providing full type safety when using the package in TypeScript projects.
153+

‎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)