diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index 341e441ee..551803e05 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -8,6 +8,7 @@ - [What Just Happened?](./what-just-happened.md) - [What Else Can We Do?](./what-else-can-we-do.md) - [Closures](./closures.md) +- [No ES Modules](./no-esm.md) - [Feature Reference](./feature-reference.md) - [CLI Reference](./cli-reference.md) - [Type Reference](./reference.md) diff --git a/guide/src/cli-reference.md b/guide/src/cli-reference.md index e1bea3403..8ea5719b6 100644 --- a/guide/src/cli-reference.md +++ b/guide/src/cli-reference.md @@ -19,11 +19,9 @@ some notable options are: * `--no-modules`: the default output of `wasm-bindgen` uses ES modules but this option indicates that ES modules should not be used and output should be - tailored for a web browser. In this mode `window.wasm_bindgen` will be a - function that takes a path to the wasm file to fetch and instantiate. - Afterwards exported functions from the wasm are available through - `window.wasm_bindgen.foo`. Note that the name `wasm_bindgen` can be configured - with the `--no-modules-global FOO` flag. + tailored for a web browser. More information on this flag, and + `--no-modules-global`, can be found in the [no ES modules + documentation](./no-esm.html). * `--no-typescript`: by default a `*.d.ts` file is generated for the generated JS file, but this flag will disable generating this TypeScript file. diff --git a/guide/src/no-esm.md b/guide/src/no-esm.md new file mode 100644 index 000000000..25465de54 --- /dev/null +++ b/guide/src/no-esm.md @@ -0,0 +1,79 @@ +# No ES Modules + +Explained a bit more in the [internal design](design.html) section one of the +key foundational principles of `wasm-bindgen` is ES modules. It supports working +without ES modules, however! Not all JS tooling and browsers are ready for ES +modules by default, so it can sometimes be helpful to quickly get up and running +without them to kick the tires and see how `wasm-bindgen` works. + +Let's start out with our hello-world example from previous chapters, and you can +also [follow along in the repository][repo]. + +[repo]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/no_modules + +```rust +#[wasm_bindgen] +extern { + fn alert(msg: &str); +} + +#[wasm_bindgen] +pub fn greet(name: &str) -> String { + alert(&format!("Hello, {}!", name); +} +``` + +Like usual, we first compile this to wasm: + +``` +$ cargo build --target wasm32-unknown-unknown +``` + +Next, to avoid using ES modules, pass the `--no-modules` option to the +`wasm-bindgen` command: + +``` +$ wasm-bindgen target/wasm32-unknown-unknown/debug/hello.wasm --no-modules --out-dir . +``` + +Next up we need to write some HTML to interact with the wasm: + +```html + + + + + + +``` + +and that's it! If you open up that web page in a browser (needs to be over HTTP) +then you should see an alert for "Hello, World!". + +The `--no-modules` output will not instantiate or compile the wasm module when +included on a web page, instead it just parses and configures the JS bindings +for the wasm-module-to-be. The page is configured with one exported global, in +this case `wasm_bindgen`. The name of this global can be configured with the +`--no-modules-global` option. + +The global `wasm_bindgen` is a function that takes one argument, the path to the +wasm file. When invoked `wasm_bindgen` will return a promise for when the wasm +file is ready-to-go. After that all exported functionality on +`wasm_bindgen` will be functional. + +In the example above, after calling `wasm_bindgen('./hello_bg.wasm')` we wait +for the wasm module to be compiled, and afterwards we're invoking our `greet` +export. + +Note that exports are available for binding before the wasm module has been +instantiated, for example this would have also worked: + +```js +const { greet } = wasm_bindgen; + +wasm_bindgen('./hello_bg.wasm') + .then(() => greet('World')); +```