The wasm-bindgen Command Line Interface

The wasm-bindgen command line tool has a number of options available to it to tweak the JavaScript that is generated. The most up-to-date set of flags can always be listed via wasm-bindgen --help.

Installation

cargo install -f wasm-bindgen-cli

Usage

wasm-bindgen [options] ./target/wasm32-unknown-unknown/release/crate.wasm

Options

--out-dir DIR

The target directory to emit the JavaScript bindings, TypeScript definitions, processed .wasm binary, etc...

--target

This flag indicates what flavor of output what wasm-bindgen should generate. For example it could generate code to be loaded in a bundler like Webpack, a native web page, or Node.js. For a full list of options to pass this flag, see the section on deployment

--no-modules-global VAR

When --target no-modules is used this flag can indicate what the name of the global to assign generated bindings to.

For more information about this see the section on deployment

--typescript

Output a TypeScript declaration file for the generated JavaScript bindings. This is on by default.

--no-typescript

By default, a *.d.ts TypeScript declaration file is generated for the generated JavaScript bindings, but this flag will disable that.

--omit-imports

When the module attribute is used with the wasm-bindgen macro, the code generator will emit corresponding import or require statements in the header section of the generated javascript. This flag causes those import statements to be omitted. This is necessary for some use cases, such as generating javascript which is intended to be used with Electron (with node integration disabled), where the imports are instead handled through a separate preload script.

--debug

Generates a bit more JS and Wasm in "debug mode" to help catch programmer errors, but this output isn't intended to be shipped to production.

--no-demangle

When post-processing the .wasm binary, do not demangle Rust symbols in the "names" custom section.

--keep-lld-exports

When post-processing the .wasm binary, do not remove exports that are synthesized by Rust's linker, LLD.

--keep-debug

When post-processing the .wasm binary, do not strip DWARF debug info custom sections. See debug information for more.

--split-debug-info

Write the DWARF debug info to a separate <name>_bg.debug.wasm file next to the main <name>_bg.wasm file. The main file gets an external_debug_info custom section that holds the URL of the debug info file. This flag implies --keep-debug. See debug information for more.

--debug-info-url <URL>

Set the URL that --split-debug-info records in the main file. The default is the file name of the debug info file, which resolves relative to the URL of the main file. Give an absolute URL if you debug with VS Code: its debugger cannot resolve a relative URL. This option requires --split-debug-info.

--browser

When generating bundler-compatible code (see the section on deployment) this indicates that the bundled code is always intended to go into a browser so a few checks for Node.js can be elided.

--omit-default-module-path

Don't add WebAssembly fallback imports in generated JavaScript.

--split-linked-modules

Controls whether wasm-bindgen will split linked modules out into their own files. Enabling this is recommended, because it allows lazy-loading the linked modules and setting a stricter Content Security Policy.

wasm-bindgen uses the new URL('…', import.meta.url) syntax to resolve the links to such split out files. This breaks with most bundlers, since the bundler doesn't know to include the linked module in its output. That's why this option is disabled by default. Webpack 5 is an exception, which has special treatment for that syntax.

For other bundlers, you'll need to take extra steps to get it to work, likely by using a plugin. Alternatively, you can leave the syntax as is and instead manually configure the bundler to copy all files in snippets/ to the output directory, preserving their paths relative to whichever bundled file ends up containing the JS shim.

On the no-modules target, link_to! won't work if used outside of a document, e.g. inside a worker. This is because it's impossible to figure out what the URL of the linked module is without a reference point like import.meta.url.

--ts-typed-array-buffers

Since TypeScript 5.7, typed arrays are generic over their backing buffer, and a bare Uint8Array means Uint8Array<ArrayBufferLike>. Several web APIs (e.g. new Blob([...]), BlobPart) only accept views over a non-shared ArrayBuffer.

Owned typed-array return values (Rust Vec<u8>, Box<[u8]>, and friends) are always copied out of the Wasm memory into a fresh, non-shared ArrayBuffer, so with this flag enabled the generated TypeScript declares them as Uint8Array<ArrayBuffer> (and similar for the other typed arrays), allowing them to flow into such APIs without a cast.

Argument types keep the bare Uint8Array form, since callers may legitimately pass views into shared memory.

This flag is off by default because the generic syntax is a type error for consumers on TypeScript 5.6 and earlier.

--force-enable-abort-handler

Emits the hard-abort detection and abort-handler machinery even when building with panic=abort.

With panic=unwind this machinery is generated automatically, since the module already contains the exception-handling instructions it relies on. A panic=abort build has no such instructions, so the abort hook registered via set_on_abort is never invoked unless this flag is passed. The flag does nothing for panic=unwind builds.

See Handling Aborts for the set_on_abort API.