# Package Output Structure

Understand the structure and contents of the JavaScript package generated by the `swift package js` command.

## Overview

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

## Package Structure

The output package has the following structure:

```
.build/plugins/PackageToJS/outputs/Package/
├── ProductName.wasm          # Compiled WebAssembly module
├── index.js                  # Main entry point for browser environments
├── index.d.ts                # TypeScript type definitions for index.js
├── instantiate.js            # Low-level instantiation API
├── instantiate.d.ts          # TypeScript type definitions for instantiate.js
├── package.json              # npm package metadata
└── platforms/
    ├── browser.js            # Browser-specific platform setup
    ├── browser.d.ts          # TypeScript definitions for browser.js
    ├── node.js               # Node.js-specific platform setup
    └── node.d.ts             # TypeScript definitions for node.js
```

## Using the Package

### In Browser

```html
<!DOCTYPE html>
<html>
<body>
  <script type="module">
    import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';
    await init();
  </script>
</body>
</html>
```

### In Node.js

```javascript
import { instantiate } from './.build/plugins/PackageToJS/outputs/Package/instantiate.js';
import { defaultNodeSetup } from './.build/plugins/PackageToJS/outputs/Package/platforms/node.js';

async function main() {
    const options = await defaultNodeSetup();
    await instantiate(options);
}

main();
```

> Tip: For a complete Node.js setup example, see the [Node.js example](https://github.com/swiftwasm/JavaScriptKit/tree/main/Examples/NodeJS).

### With Bundlers (Vite, Webpack, etc.)

The generated package can be consumed by JavaScript bundlers:

```bash
npm install .build/plugins/PackageToJS/outputs/Package
```

Then import it in your JavaScript code:

```javascript
import { init } from 'package-name';
await init();
```

## Core Files

### WebAssembly Module (`ProductName.wasm`)

The compiled WebAssembly binary containing your Swift code. The filename matches your SwiftPM product name (e.g., `Basic.wasm` for a product named "Basic").

### Entry Point (`index.js`)

The main entry point for browser environments. It provides a convenient `init()` function that handles module instantiation with default settings.

```javascript
import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';

// Initialize with default browser setup
await init();
```

For packages with BridgeJS imports, you can provide custom imports:

```javascript
import { init } from './.build/plugins/PackageToJS/outputs/Package/index.js';

await init({
    getImports: () => ({
        // Your custom imports
    })
});
```

### Instantiation API (`instantiate.js`)

A lower-level API for more control over module instantiation. Use this when you need to customize the WebAssembly instantiation process or WASI setup.

```javascript
import { instantiate } from './.build/plugins/PackageToJS/outputs/Package/instantiate.js';
import { defaultBrowserSetup } from './.build/plugins/PackageToJS/outputs/Package/platforms/browser.js';

const options = await defaultBrowserSetup({
    module: fetch('./ProductName.wasm'),
    // ... other options
});

const { instance, swift, exports } = await instantiate(options);
```

### Platform-Specific Setup

The `platforms/` directory contains platform-specific setup functions:
- `platforms/browser.js` - Provides `defaultBrowserSetup()` for browser environments
- `platforms/node.js` - Provides `defaultNodeSetup()` for Node.js environments

## Package Metadata (`package.json`)

The generated `package.json` includes:

```json
{
    "name": "package-name",
    "version": "0.0.0",
    "type": "module",
    "private": true,
    "exports": {
        ".": "./index.js",
        "./wasm": "./ProductName.wasm"
    },
    "dependencies": {
        "@bjorn3/browser_wasi_shim": "0.3.0"
    }
}
```

The `exports` field allows importing the package as an npm dependency:

```javascript
import { init } from '.build/plugins/PackageToJS/outputs/Package';
```

## TypeScript Support

All JavaScript files have corresponding `.d.ts` TypeScript definition files, providing full type safety when using the package in TypeScript projects.

