agent-skills/skills/tsdown/references/recipe-wasm.md

WASM Support

Bundle WebAssembly modules in your TypeScript/JavaScript project.

Overview

tsdown supports WASM through rolldown-plugin-wasm, enabling direct .wasm imports with synchronous and asynchronous instantiation.

Setup

Install

pnpm add -D rolldown-plugin-wasm

Configure

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:

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

Importing WASM Modules

Direct Import

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

Async Init

Use ?init query for async initialization:

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:

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

wasm-bindgen Support

Target bundler (Recommended)

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

Target web (Node.js)

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)

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

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 - Plugin system overview
• Platform - Target platform configuration