Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/reference/deployment.md

raw
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/