#lib.wasm

• Type:

type Wasm =
  | boolean
  | {
      mode?: 'portable' | 'inline' | 'asset' | 'rspack-runtime';
      url?: boolean | { mode?: 'preserve' | 'rewrite' };
      module?: boolean | { enabled?: boolean };
      glue?: boolean | { enabled?: boolean };
      inline?: boolean | 'auto';
      inlineLimit?: number;
      assetFileName?: string;
    };

• Default: false

Configure WebAssembly (.wasm) support for library output.

#Boolean type

Set wasm: true to enable WASM support with the default behavior:

export default {
  lib: [
    {
      format: 'esm',
      wasm: true,
    },
  ],
};

By default, Rslib supports:

• new URL('./foo.wasm', import.meta.url) references;
• ESM .wasm imports and re-exports;
• local JavaScript glue files that reference companion .wasm assets with new URL() in bundleless output.

Set wasm: false or omit this option to disable WASM support.

#Object type

Use an object to customize each part of WASM handling:

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        url: true,
        module: true,
        glue: true,
        inline: 'auto',
        inlineLimit: 14 * 1024,
        assetFileName: 'static/wasm/[name].[contenthash:8][ext]',
      },
    },
  ],
};

#wasm.mode

• Type: 'portable' | 'inline' | 'asset' | 'rspack-runtime'
• Default: 'portable'

Controls the overall WASM output strategy.

#portable

The default strategy. Rslib handles standard new URL() references, ESM .wasm imports, and local JavaScript glue companion assets with portable ESM output.

#inline

Forces raw ESM .wasm imports to inline wasm bytes into the generated JavaScript facade.

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        mode: 'inline',
      },
    },
  ],
};

#asset

Forces raw ESM .wasm imports to emit the wasm file as a separate asset and load it from the generated JavaScript facade.

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        mode: 'asset',
      },
    },
  ],
};

#rspack-runtime

Uses Rspack's WebAssembly runtime handling instead of Rslib's portable WASM handling. This enables Rspack's asyncWebAssembly experiment.

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        mode: 'rspack-runtime',
      },
    },
  ],
};

This mode is useful when you control the consuming application environment, but it is not recommended as the default output strategy for portable libraries.

#wasm.url

• Type: boolean | { mode?: 'preserve' | 'rewrite' }
• Default: true

Controls support for standard new URL('./foo.wasm', import.meta.url) references.

When enabled, Rslib scans JavaScript and TypeScript modules for static .wasm URL references, emits the referenced .wasm file, and preserves or rewrites the URL according to wasm.url.mode.

export const wasmUrl = new URL('./foo.wasm', import.meta.url);

Set wasm.url to false to disable this handling.

#wasm.url.mode

• Type: 'preserve' | 'rewrite'
• Default: 'preserve'

'preserve' keeps the original relative request in the generated JavaScript output and emits the .wasm file to the corresponding output location.

'rewrite' emits the .wasm file using wasm.assetFileName and rewrites the URL to the emitted asset path.

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        url: {
          mode: 'rewrite',
        },
        assetFileName: 'static/wasm/[name].[contenthash:8][ext]',
      },
    },
  ],
};

#wasm.module

• Type: boolean | { enabled?: boolean }
• Default: true

Controls support for ESM .wasm imports and re-exports.

import { add } from './add.wasm';

export { add };
export * from './add.wasm';

When enabled, Rslib transforms the .wasm module into a JavaScript ESM facade. The facade instantiates the WebAssembly module and re-exports the wasm exports.

Set wasm.module to false or { enabled: false } to disable this handling.

#wasm.glue

• Type: boolean | { enabled?: boolean }
• Default: true

Controls bundleless handling for local JavaScript glue files.

In bundled output, JavaScript glue files are processed through the same module pipeline as other JavaScript modules, so standard new URL('./foo.wasm', import.meta.url) references are handled by wasm.url.

In bundleless output, local JavaScript glue files may be preserved as separate files. When wasm.glue is enabled, Rslib scans those local glue files for standard new URL() .wasm references and emits the companion .wasm files next to the generated glue output.

This option is useful for ESM glue generated by tools such as wasm-pack --target web or wasm-bindgen when the generated glue references a companion .wasm file with new URL().

Set wasm.glue to false or { enabled: false } to disable bundleless glue scanning.

#wasm.inline

• Type: boolean | 'auto'
• Default: 'auto'

Controls whether raw ESM .wasm imports are inlined into the generated JavaScript facade.

• true: always inline raw .wasm module bytes.
• false: do not inline raw .wasm module bytes.
• 'auto': inline raw .wasm module bytes when the file size is less than or equal to wasm.inlineLimit.

This option only applies to ESM .wasm imports handled by wasm.module. It does not patch existing JavaScript glue code.

#wasm.inlineLimit

• Type: number
• Default: 14336

The maximum file size in bytes for wasm.inline: 'auto'.

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        inline: 'auto',
        inlineLimit: 14 * 1024,
      },
    },
  ],
};

#wasm.assetFileName

• Type: string
• Default: 'static/wasm/[name].[contenthash:8][ext]'

The filename template for emitted .wasm assets.

Supported placeholders:

• [name]: file name without extension.
• [base]: file name with extension.
• [ext]: file extension.
• [hash] or [contenthash]: content hash.
• [hash:N] or [contenthash:N]: content hash with length N.

export default {
  lib: [
    {
      format: 'esm',
      wasm: {
        assetFileName: 'assets/[name].[contenthash:8][ext]',
      },
    },
  ],
};

#See also

See WebAssembly for examples, runtime notes, and wasm-pack / wasm-bindgen guidance.