| 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]. |