Add more documentation for --no-modules (#526)

Closes #211
2024-11-28 23:14:12 +03:00 · 2018-07-20 12:00:51 -05:00 · 2018-07-20 12:00:51 -05:00 · 61ef250dca
commit 61ef250dca
parent 801d62ae68
3 changed files with 83 additions and 5 deletions
--- 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)
--- 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.
--- a/guide/src/no-esm.md
+++ 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
+<html>
+  <body>
+    <script src='./hello.js'></script>
+    <script>
+      wasm_bindgen('./hello_bg.wasm')
+        .then(() => wasm_bindgen.greet('World'));
+    </script>
+  </body>
+</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'));
+```