| 1 |
# Deploying Rust and WebAssembly |
| 2 |
|
| 3 |
At this point in time deploying Rust and WebAssembly to the web or other |
| 4 |
locations unfortunately isn't a trivial task to do. This page hopes to serve |
| 5 |
as documentation for the various known options, and as always PRs are welcome |
| 6 |
to update this if it's out of date! |
| 7 |
|
| 8 |
The methods of deployment and integration here are primarily tied to the |
| 9 |
`--target` flag. |
| 10 |
|
| 11 |
| Value | Summary | |
| 12 |
|-----------------|------------------------------------------------------------| |
| 13 |
| [`bundler`] | Suitable for loading in bundlers like Webpack | |
| 14 |
| [`web`] | Directly loadable in a web browser | |
| 15 |
| [`nodejs`] | Loadable via `require` as a Node.js module | |
| 16 |
| [`deno`] | Loadable using imports from Deno modules | |
| 17 |
| [`no-modules`] | Like `web`, but older and doesn't use ES modules | |
| 18 |
|
| 19 |
[`bundler`]: #bundlers |
| 20 |
[`web`]: #without-a-bundler |
| 21 |
[`no-modules`]: #without-a-bundler |
| 22 |
[`nodejs`]: #nodejs |
| 23 |
[`deno`]: #deno |
| 24 |
|
| 25 |
## Bundlers |
| 26 |
|
| 27 |
**`--target bundler`** |
| 28 |
|
| 29 |
The default output of `wasm-bindgen`, or the `bundler` target, assumes a model |
| 30 |
where the wasm module itself is natively an ES module. This model, however, is not |
| 31 |
natively implemented in any JS implementation at this time. As a result, to |
| 32 |
consume the default output of `wasm-bindgen` you will need a bundler of some |
| 33 |
form. |
| 34 |
|
| 35 |
> **Note**: the choice of this default output was done to reflect the trends of |
| 36 |
> the JS ecosystem. While tools other than bundlers don't support wasm files as |
| 37 |
> native ES modules today they're all very much likely to in the future! |
| 38 |
|
| 39 |
Currently the only known bundler known to be fully compatible with |
| 40 |
`wasm-bindgen` is [webpack]. Most [examples] use webpack, and you can check out |
| 41 |
the [hello world example online] to see the details of webpack configuration |
| 42 |
necessary. |
| 43 |
|
| 44 |
[webpack]: https://webpack.js.org/ |
| 45 |
[examples]: ../examples/index.html |
| 46 |
[hello world example online]: ../examples/hello-world.html |
| 47 |
|
| 48 |
## Without a Bundler |
| 49 |
|
| 50 |
**`--target web` or `--target no-modules`** |
| 51 |
|
| 52 |
If you're not using a bundler but you're still running code in a web browser, |
| 53 |
`wasm-bindgen` still supports this! For this use case you'll want to use the |
| 54 |
`--target web` flag. You can check out a [full example][nomex] in the |
| 55 |
documentation, but the highlights of this output are: |
| 56 |
|
| 57 |
* When compiling you'll pass `--target web` to `wasm-bindgen` |
| 58 |
* The output can natively be included on a web page, and doesn't require any |
| 59 |
further postprocessing. The output is included as an ES module. |
| 60 |
* The `--target web` mode is not able to use NPM dependencies. |
| 61 |
* You'll want to review the [browser requirements] for `wasm-bindgen` because |
| 62 |
no polyfills will be available. |
| 63 |
|
| 64 |
[nomex]: ../examples/without-a-bundler.html |
| 65 |
[rfc1]: https://github.com/rustwasm/rfcs/pull/6 |
| 66 |
[rfc2]: https://github.com/rustwasm/rfcs/pull/8 |
| 67 |
[browser requirements]: browser-support.html |
| 68 |
|
| 69 |
The CLI also supports an output mode called `--target no-modules` which is |
| 70 |
similar to the `web` target in that it requires manual initialization of the |
| 71 |
wasm and is intended to be included in web pages without any further |
| 72 |
postprocessing. See the [without a bundler example][nomex] for some more |
| 73 |
information about `--target no-modules`. |
| 74 |
|
| 75 |
## Node.js |
| 76 |
|
| 77 |
**`--target nodejs`** |
| 78 |
|
| 79 |
If you're deploying WebAssembly into Node.js (perhaps as an alternative to a |
| 80 |
native module), then you'll want to pass the `--target nodejs` flag to `wasm-bindgen`. |
| 81 |
|
| 82 |
Like the "without a bundler" strategy, this method of deployment does not |
| 83 |
require any further postprocessing. The generated JS shims can be `require`'d |
| 84 |
just like any other Node module (even the `*_bg` wasm file can be `require`'d |
| 85 |
as it has a JS shim generated as well). |
| 86 |
|
| 87 |
Note that this method requires a version of Node.js with WebAssembly support, |
| 88 |
which is currently Node 8 and above. |
| 89 |
|
| 90 |
## Deno |
| 91 |
|
| 92 |
**`--target deno`** |
| 93 |
|
| 94 |
To deploy WebAssembly to Deno, use the `--target deno` flag. |
| 95 |
To then import your module inside deno, use |
| 96 |
|
| 97 |
```ts |
| 98 |
// @deno-types="./out/crate_name.d.ts" |
| 99 |
import { yourFunction } from "./out/crate_name.js"; |
| 100 |
``` |
| 101 |
|
| 102 |
## NPM |
| 103 |
|
| 104 |
If you'd like to deploy compiled WebAssembly to NPM, then the tool for the job |
| 105 |
is [`wasm-pack`]. More information on this coming soon! |
| 106 |
|
| 107 |
[`wasm-pack`]: https://rustwasm.github.io/docs/wasm-pack/ |