| 1 |
# The `wasm-bindgen` Command Line Interface |
| 2 |
|
| 3 |
The `wasm-bindgen` command line tool has a number of options available to it to |
| 4 |
tweak the JavaScript that is generated. The most up-to-date set of flags can |
| 5 |
always be listed via `wasm-bindgen --help`. |
| 6 |
|
| 7 |
## Installation |
| 8 |
|
| 9 |
``` |
| 10 |
cargo install -f wasm-bindgen-cli |
| 11 |
``` |
| 12 |
|
| 13 |
## Usage |
| 14 |
|
| 15 |
``` |
| 16 |
wasm-bindgen [options] ./target/wasm32-unknown-unknown/release/crate.wasm |
| 17 |
``` |
| 18 |
|
| 19 |
## Options |
| 20 |
|
| 21 |
### `--out-dir DIR` |
| 22 |
|
| 23 |
The target directory to emit the JavaScript bindings, TypeScript definitions, |
| 24 |
processed `.wasm` binary, etc... |
| 25 |
|
| 26 |
### `--target` |
| 27 |
|
| 28 |
This flag indicates what flavor of output what `wasm-bindgen` should generate. |
| 29 |
For example it could generate code to be loaded in a bundler like Webpack, a |
| 30 |
native web page, or Node.js. For a full list of options to pass this flag, see |
| 31 |
the section on [deployment] |
| 32 |
|
| 33 |
[deployment]: deployment.html |
| 34 |
|
| 35 |
### `--no-modules-global VAR` |
| 36 |
|
| 37 |
When `--target no-modules` is used this flag can indicate what the name of the |
| 38 |
global to assign generated bindings to. |
| 39 |
|
| 40 |
For more information about this see the section on [deployment] |
| 41 |
|
| 42 |
### `--typescript` |
| 43 |
|
| 44 |
Output a TypeScript declaration file for the generated JavaScript bindings. This |
| 45 |
is on by default. |
| 46 |
|
| 47 |
### `--no-typescript` |
| 48 |
|
| 49 |
By default, a `*.d.ts` TypeScript declaration file is generated for the |
| 50 |
generated JavaScript bindings, but this flag will disable that. |
| 51 |
|
| 52 |
### `--omit-imports` |
| 53 |
|
| 54 |
When the `module` attribute is used with the `wasm-bindgen` macro, the code |
| 55 |
generator will emit corresponding `import` or `require` statements in the header |
| 56 |
section of the generated javascript. This flag causes those import statements to |
| 57 |
be omitted. This is necessary for some use cases, such as generating javascript |
| 58 |
which is intended to be used with Electron (with node integration disabled), |
| 59 |
where the imports are instead handled through a separate preload script. |
| 60 |
|
| 61 |
### `--debug` |
| 62 |
|
| 63 |
Generates a bit more JS and wasm in "debug mode" to help catch programmer |
| 64 |
errors, but this output isn't intended to be shipped to production. |
| 65 |
|
| 66 |
### `--no-demangle` |
| 67 |
|
| 68 |
When post-processing the `.wasm` binary, do not demangle Rust symbols in the |
| 69 |
"names" custom section. |
| 70 |
|
| 71 |
### `--keep-lld-exports` |
| 72 |
|
| 73 |
When post-processing the `.wasm` binary, do not remove exports that are |
| 74 |
synthesized by Rust's linker, LLD. |
| 75 |
|
| 76 |
### `--keep-debug` |
| 77 |
|
| 78 |
When post-processing the `.wasm` binary, do not strip DWARF debug info custom |
| 79 |
sections. |
| 80 |
|
| 81 |
### `--browser` |
| 82 |
|
| 83 |
When generating bundler-compatible code (see the section on [deployment]) this |
| 84 |
indicates that the bundled code is always intended to go into a browser so a few |
| 85 |
checks for Node.js can be elided. |
| 86 |
|
| 87 |
### `--reference-types` |
| 88 |
|
| 89 |
Enables usage of the [WebAssembly References Types |
| 90 |
proposal](https://github.com/webassembly/reference-types) proposal, meaning that |
| 91 |
the WebAssembly binary will use `externref` when importing and exporting |
| 92 |
functions that work with `JsValue`. For more information see the [documentation |
| 93 |
about reference types](./reference-types.md). |
| 94 |
|
| 95 |
### `--omit-default-module-path` |
| 96 |
|
| 97 |
Don't add WebAssembly fallback imports in generated JavaScript. |
| 98 |
|
| 99 |
### `--split-linked-modules` |
| 100 |
|
| 101 |
Controls whether wasm-bindgen will split linked modules out into their own |
| 102 |
files. Enabling this is recommended, because it allows lazy-loading the linked |
| 103 |
modules and setting a stricter Content Security Policy. |
| 104 |
|
| 105 |
wasm-bindgen uses the `new URL('…', import.meta.url)` syntax to resolve the |
| 106 |
links to such split out files. This breaks with most bundlers, since the bundler |
| 107 |
doesn't know to include the linked module in its output. That's why this option |
| 108 |
is disabled by default. Webpack 5 is an exception, which has special treatment |
| 109 |
for that syntax. |
| 110 |
|
| 111 |
For other bundlers, you'll need to take extra steps to get it to work, likely by |
| 112 |
using a plugin. Alternatively, you can leave the syntax as is and instead |
| 113 |
manually configure the bundler to copy all files in `snippets/` to the output |
| 114 |
directory, preserving their paths relative to whichever bundled file ends up |
| 115 |
containing the JS shim. |
| 116 |
|
| 117 |
On the no-modules target, `link_to!` won't work if used outside of a document, |
| 118 |
e.g. inside a worker. This is because it's impossible to figure out what the |
| 119 |
URL of the linked module is without a reference point like `import.meta.url`. |