stack/v1/packages/mosaic/framework/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