Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/reference/js-snippets.md

raw
1 # JS Snippets
2
3 Often when developing a crate you want to run on the web you'll want to include
4 some JS code here and there. While [`js-sys`](https://docs.rs/js-sys) and
5 [`web-sys`](https://docs.rs/web-sys) cover many needs they don't cover
6 everything, so `wasm-bindgen` supports the ability to write JS code next to your
7 Rust code and have it included in the final output artifact.
8
9 To include a local JS file, you'll use the `#[wasm_bindgen(module)]` macro:
10
11 ```rust
12 #[wasm_bindgen(module = "/js/foo.js")]
13 extern "C" {
14 fn add(a: u32, b: u32) -> u32;
15 }
16 ```
17
18 This declaration indicates that all the functions contained in the `extern`
19 block are imported from the file `/js/foo.js`, where the root is relative to the
20 crate root (where `Cargo.toml` is located).
21
22 The `/js/foo.js` file will make its way to the final output when `wasm-bindgen`
23 executes, so you can use the `module` annotation in a library without having to
24 worry users of your library!
25
26 The JS file itself must be written with ES module syntax:
27
28 ```js
29 export function add(a, b) {
30 return a + b;
31 }
32 ```
33
34 A full design of this feature can be found in [RFC 6] as well if you're
35 interested!
36
37 [RFC 6]: https://github.com/rustwasm/rfcs/pull/6
38
39 ### Using `inline_js`
40
41 In addition to `module = "..."` if you're a macro author you also have the
42 ability to use the `inline_js` attribute:
43
44 ```rust
45 #[wasm_bindgen(inline_js = "export function add(a, b) { return a + b; }")]
46 extern "C" {
47 fn add(a: u32, b: u32) -> u32;
48 }
49 ```
50
51 Using `inline_js` indicates that the JS module is specified inline in the
52 attribute itself, and no files are loaded from the filesystem. They have the
53 same limitations and caveats as when using `module`, but can sometimes be easier
54 to generate for macros themselves. It's not recommended for hand-written code to
55 make use of `inline_js` but instead to leverage `module` where possible.
56
57 ### Caveats
58
59 While quite useful local JS snippets currently suffer from a few caveats which
60 are important to be aware of. Many of these are temporary though!
61
62 * Currently `import` statements are not supported in the JS file. This is a
63 restriction we may lift in the future once we settle on a good way to support
64 this. For now, though, js snippets must be standalone modules and can't import
65 from anything else.
66
67 * Only `--target web` and the default bundler output mode are supported. To
68 support `--target nodejs` we'd need to translate ES module syntax to CommonJS
69 (this is
70 planned to be done, just hasn't been done yet). Additionally to support
71 `--target no-modules` we'd have to similarly translate from ES modules to
72 something else.
73
74 * Paths in `module = "..."` must currently start with `/`, or be rooted at the
75 crate root. It is intended to eventually support relative paths like `./` and
76 `../`, but it's currently believed that this requires more support in
77 the Rust `proc_macro` crate.
78
79 As above, more detail about caveats can be found in [RFC 6].