# WASM Support

Bundle WebAssembly modules in your TypeScript/JavaScript project.

## Overview

tsdown supports WASM through [`rolldown-plugin-wasm`](https://github.com/sxzz/rolldown-plugin-wasm), enabling direct `.wasm` imports with synchronous and asynchronous instantiation.

## Setup

### Install

```bash
pnpm add -D rolldown-plugin-wasm
```

### Configure

```ts
import { wasm } from 'rolldown-plugin-wasm'
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['./src/index.ts'],
  plugins: [wasm()],
})
```

### TypeScript Support

Add type declarations to `tsconfig.json`:

```jsonc
{
  "compilerOptions": {
    "types": ["rolldown-plugin-wasm/types"]
  }
}
```

## Importing WASM Modules

### Direct Import

```ts
import { add } from './add.wasm'
add(1, 2)
```

### Async Init

Use `?init` query for async initialization:

```ts
import init from './add.wasm?init'
const instance = await init(imports) // imports optional
instance.exports.add(1, 2)
```

### Sync Init

Use `?init&sync` query for synchronous initialization:

```ts
import initSync from './add.wasm?init&sync'
const instance = initSync(imports) // imports optional
instance.exports.add(1, 2)
```

## wasm-bindgen Support

### Target `bundler` (Recommended)

```ts
import { add } from 'some-pkg'
add(1, 2)
```

### Target `web` (Node.js)

```ts
import { readFile } from 'node:fs/promises'
import init, { add } from 'some-pkg'
import wasmUrl from 'some-pkg/add_bg.wasm?url'

await init({
  module_or_path: readFile(new URL(wasmUrl, import.meta.url)),
})
add(1, 2)
```

### Target `web` (Browser)

```ts
import init, { add } from 'some-pkg/add.js'
import wasmUrl from 'some-pkg/add_bg.wasm?url'

await init({ module_or_path: wasmUrl })
add(1, 2)
```

`nodejs` and `no-modules` wasm-bindgen targets are not supported.

## Plugin Options

```ts
wasm({
  maxFileSize: 14 * 1024, // Max size for inline (default: 14KB)
  fileName: '[hash][extname]', // Output file name pattern
  publicPath: '',         // Prefix for non-inlined file paths
  targetEnv: 'auto',      // 'auto' | 'auto-inline' | 'browser' | 'node'
})
```

| Option | Default | Description |
|--------|---------|-------------|
| `maxFileSize` | `14 * 1024` | Max file size for inlining. Set to `0` to always copy. |
| `fileName` | `'[hash][extname]'` | Pattern for emitted WASM files |
| `publicPath` | — | Prefix for non-inlined WASM file paths |
| `targetEnv` | `'auto'` | `'auto'` detects at runtime; `'browser'` omits Node builtins; `'node'` omits fetch |

## Related Options

- [Plugins](advanced-plugins.md) - Plugin system overview
- [Platform](option-platform.md) - Target platform configuration