Switch the --browser argument to --web

This commit reverts part of the implementation of [RFC 6]. That RFC
specified that the `--browser` flag was going to be repurposed for the
new "natively loadable as ES module output", but unfortunately the
breakage is far broader than initially expected. It turns out that
`wasm-pack` passes `--browser` by default which means that a change to
break `--browser` would break all historical versions of `wasm-pack`
which is a bit much for now.

To solve this the `--browser` flag is going back to what it represents
on the current released version of `wasm-bindgen` (optimize away some
node.js checks in a few places for bundler-style output) and a new
`--web` flag is being introduced as the new deployment strategy.

[RFC 6]: rustwasm/rfcs#6

Closes wasm-bindgen#1318

Author: alexcrichton

crates/cli-support/src/js/mod.rs

@@ -166,7 +166,7 @@ impl<'a> Context<'a> {
                     format!("__exports.{} = {};\n", name, contents)
                 }
             }
-            OutputMode::Bundler
+            OutputMode::Bundler { .. }
             | OutputMode::Node {
                 experimental_modules: true,
             } => {
@@ -178,7 +178,7 @@ impl<'a> Context<'a> {
                     format!("export const {} = {};\n", name, contents)
                 }
             }
-            OutputMode::Browser => {
+            OutputMode::Web => {
                 // In browser mode there's no need to export the internals of
                 // wasm-bindgen as we're not using the module itself as the
                 // import object but rather the `__exports` map we'll be
@@ -202,7 +202,7 @@ impl<'a> Context<'a> {
         };
         self.global(&global);
 
-        if self.config.mode.browser() {
+        if self.config.mode.web() {
             self.global(&format!("__exports.{} = {0};", name));
         }
     }
@@ -300,7 +300,7 @@ impl<'a> Context<'a> {
     }
 
     /// Performs the task of actually generating the final JS module, be it
-    /// `--no-modules`, `--browser`, or for bundlers. This is the very last step
+    /// `--no-modules`, `--web`, or for bundlers. This is the very last step
     /// performed in `finalize`.
     fn finalize_js(&mut self, module_name: &str, needs_manual_start: bool) -> (String, String) {
         let mut js = String::new();
@@ -340,7 +340,7 @@ impl<'a> Context<'a> {
             // With Bundlers and modern ES6 support in Node we can simply import
             // the wasm file as if it were an ES module and let the
             // bundler/runtime take care of it.
-            OutputMode::Bundler
+            OutputMode::Bundler { .. }
             | OutputMode::Node {
                 experimental_modules: true,
             } => {
@@ -354,7 +354,7 @@ impl<'a> Context<'a> {
             // browsers don't support natively importing wasm right now so we
             // expose the same initialization function as `--no-modules` as the
             // default export of the module.
-            OutputMode::Browser => {
+            OutputMode::Web => {
                 js.push_str("const __exports = {};\n");
                 self.imports_post.push_str("let wasm;\n");
                 init = self.gen_init(&module_name, needs_manual_start);
@@ -752,10 +752,10 @@ impl<'a> Context<'a> {
         })?;
 
         self.bind("__wbindgen_module", &|me| {
-            if !me.config.mode.no_modules() && !me.config.mode.browser() {
+            if !me.config.mode.no_modules() && !me.config.mode.web() {
                 bail!(
                     "`wasm_bindgen::module` is currently only supported with \
-                     --no-modules"
+                     --no-modules and --web"
                 );
             }
             Ok(format!(
@@ -2843,13 +2843,13 @@ impl<'a, 'b> SubContext<'a, 'b> {
             if is_local_snippet {
                 bail!(
                     "local JS snippets are not supported with `--no-modules`; \
-                     use `--browser` or no flag instead",
+                     use `--web` or no flag instead",
                 );
             }
             if let decode::ImportModule::Named(module) = &import.module {
                 bail!(
                     "import from `{}` module not allowed with `--no-modules`; \
-                     use `--nodejs`, `--browser`, or no flag instead",
+                     use `--nodejs`, `--web`, or no flag instead",
                     module
                 );
             }

crates/cli-support/src/lib.rs

@@ -36,8 +36,8 @@ pub struct Bindgen {
 }
 
 enum OutputMode {
-    Bundler,
-    Browser,
+    Bundler { browser_only: bool },
+    Web,
     NoModules { global: String },
     Node { experimental_modules: bool },
 }
@@ -59,7 +59,7 @@ impl Bindgen {
         Bindgen {
             input: Input::None,
             out_name: None,
-            mode: OutputMode::Bundler,
+            mode: OutputMode::Bundler { browser_only: false },
             debug: false,
             typescript: false,
             demangle: true,
@@ -93,7 +93,7 @@ impl Bindgen {
 
     fn switch_mode(&mut self, mode: OutputMode, flag: &str) -> Result<(), Error> {
         match self.mode {
-            OutputMode::Bundler => self.mode = mode,
+            OutputMode::Bundler { .. } => self.mode = mode,
             _ => bail!(
                 "cannot specify `{}` with another output mode already specified",
                 flag
@@ -126,9 +126,9 @@ impl Bindgen {
         Ok(self)
     }
 
-    pub fn browser(&mut self, browser: bool) -> Result<&mut Bindgen, Error> {
-        if browser {
-            self.switch_mode(OutputMode::Browser, "--browser")?;
+    pub fn web(&mut self, web: bool) -> Result<&mut Bindgen, Error> {
+        if web {
+            self.switch_mode(OutputMode::Web, "--web")?;
         }
         Ok(self)
     }
@@ -145,6 +145,16 @@ impl Bindgen {
         Ok(self)
     }
 
+    pub fn browser(&mut self, browser: bool) -> Result<&mut Bindgen, Error> {
+        if browser {
+            match &mut self.mode {
+                OutputMode::Bundler { browser_only } => *browser_only = true,
+                _ => bail!("cannot specify `--browser` with other output types"),
+            }
+        }
+        Ok(self)
+    }
+
     pub fn no_modules_global(&mut self, name: &str) -> Result<&mut Bindgen, Error> {
         match &mut self.mode {
             OutputMode::NoModules { global } => *global = name.to_string(),
@@ -660,15 +670,16 @@ impl OutputMode {
 
     fn always_run_in_browser(&self) -> bool {
         match self {
-            OutputMode::Browser => true,
+            OutputMode::Web => true,
             OutputMode::NoModules { .. } => true,
+            OutputMode::Bundler { browser_only } => *browser_only,
             _ => false,
         }
     }
 
-    fn browser(&self) -> bool {
+    fn web(&self) -> bool {
         match self {
-            OutputMode::Browser => true,
+            OutputMode::Web => true,
             _ => false,
         }
     }

crates/cli/src/bin/wasm-bindgen-test-runner/main.rs

@@ -108,7 +108,7 @@ fn rmain() -> Result<(), Error> {
     let mut b = Bindgen::new();
     b.debug(debug)
         .nodejs(node)?
-        .browser(!node)?
+        .web(!node)?
         .input_module(module, wasm)
         .keep_debug(false)
         .emit_start(false)

crates/cli/src/bin/wasm-bindgen.rs

@@ -22,7 +22,8 @@ Options:
     --out-dir DIR                Output directory
     --out-name VAR               Set a custom output filename (Without extension. Defaults to crate name)
     --nodejs                     Generate output that only works in node.js
-    --browser                    Generate output that only works in a browser
+    --web                        Generate output that only works in a browser
+    --browser                    Hint that JS should only be compatible with a browser
     --no-modules                 Generate output that only works in a browser (without modules)
     --no-modules-global VAR      Name of the global variable to initialize
     --typescript                 Output a TypeScript definition file (on by default)
@@ -41,6 +42,7 @@ Options:
 struct Args {
     flag_nodejs: bool,
     flag_browser: bool,
+    flag_web: bool,
     flag_no_modules: bool,
     flag_typescript: bool,
     flag_no_typescript: bool,
@@ -89,6 +91,7 @@ fn rmain(args: &Args) -> Result<(), Error> {
     let mut b = Bindgen::new();
     b.input_path(input)
         .nodejs(args.flag_nodejs)?
+        .web(args.flag_web)?
         .browser(args.flag_browser)?
         .no_modules(args.flag_no_modules)?
         .debug(args.flag_debug)

examples/without-a-bundler-no-modules/README.md

@@ -14,8 +14,8 @@ and then opening `index.html` in a browser should run the example!
 
 Note that this example is in contrast to the [without a bundler][wab] example
 which performs a similar purpose except it uses `--no-modules` instead of
-`--browser`. The main difference here is how the shim JS and module are loaded,
-where this example uses old-school `script` tags while `--browser` uses ES
+`--web`. The main difference here is how the shim JS and module are loaded,
+where this example uses old-school `script` tags while `--web` uses ES
 modules.
 
 [wab]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler

examples/without-a-bundler-no-modules/index.html

@@ -7,8 +7,8 @@
     <script src='pkg/without_a_bundler_no_modules.js'></script>
 
     <script type=module>
-      // Like with the `--browser` output the exports are immediately available
-      // but they won't work until we initialize the module. Unlike `--browser`,
+      // Like with the `--web` output the exports are immediately available
+      // but they won't work until we initialize the module. Unlike `--web`,
       // however, the globals are all stored on a `wasm_bindgen` global. The
       // global itself is the initialization function and then the properties of
       // the global are all the exported functions.

examples/without-a-bundler/README.md

@@ -11,7 +11,7 @@ $ cargo build --target wasm32-unknown-unknown --release
 $ cargo run -p wasm-bindgen-cli --bin wasm-bindgen -- \
   ../../target/wasm32-unknown-unknown/release/without_a_bundler.wasm \
   --out-dir pkg \
-  --browser
+  --web
 ```
 
 and then opening `index.html` in a browser should run the example!

examples/without-a-bundler/build.sh

@@ -3,13 +3,13 @@
 set -ex
 
 # Note that typically we'd use `wasm-pack` to build the crate, but the
-# `--browser` flag is very new to `wasm-bindgen` and as such doesn't have
+# `--web` flag is very new to `wasm-bindgen` and as such doesn't have
 # support in `wasm-pack` yet. Support will be added soon though!
 
 cargo build --target wasm32-unknown-unknown --release
 cargo run --manifest-path ../../crates/cli/Cargo.toml \
     --bin wasm-bindgen -- \
     ../../target/wasm32-unknown-unknown/release/without_a_bundler.wasm --out-dir pkg \
-    --browser
+    --web
 
 python3 -m http.server

guide/src/examples/without-a-bundler.md

@@ -4,15 +4,15 @@
 
 [code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler
 
-This example shows how the `--browser` flag can be used load code in a
+This example shows how the `--web` flag can be used load code in a
 browser directly. For this deployment strategy bundlers like Webpack are not
 required. For more information on deployment see the [dedicated
 documentation][deployment].
 
-> **Note**: the `--browser` flag is quite new to `wasm-bindgen`, and does not
+> **Note**: the `--web` flag is quite new to `wasm-bindgen`, and does not
 > currently have support in `wasm-pack` yet. Support will be added soon though!
 
-First let's take a look at the code and see how when we're using `--browser`
+First let's take a look at the code and see how when we're using `--web`
 we're not actually losing any functionality!
 
 ```rust
@@ -40,7 +40,7 @@ The older version of using `wasm-bindgen` without a bundler is to use the
 `--no-modules` flag to the `wasm-bindgen` CLI. This corresponds to `--target
 no-modules` in `wasm-pack`.
 
-While similar to the newer `--browser`, the `--no-modules` flag has a few
+While similar to the newer `--web`, the `--no-modules` flag has a few
 caveats:
 
 * It does not support [local JS snippets][snippets]

guide/src/reference/cli.md

@@ -29,11 +29,17 @@ usage of `require` of the generated JS and internally using `require` instead of
 ECMAScript modules. When using this flag no further postprocessing (aka a
 bundler) should be necessary to work with the wasm.
 
-### `--browser`
+For more information about this see the section on [deployment]
+
+[deployment]: deployment.html
+
+### `--web`
+
+This flag will generate output suitable for loading natively in browsers today.
+The generated JS shims are an ES module which export a `default` instantiation
+function, like `--no-modules` below.
 
-This flag will tailor the output specifically for browsers, making it
-incompatible with Node. This will basically make the generated JS a tiny bit
-smaller as runtime checks for Node won't be necessary.
+For more information about this see the section on [deployment]
 
 ### `--no-modules` and  `--no-modules-global VAR`
 
@@ -44,8 +50,7 @@ tailored for a properties on the JavaScript global object (e.g. `window`).
 The `--no-modules-global VAR` option makes `VAR` the global property that the
 JavaScript bindings are attached to.
 
-More information can be found in the [documentation for building without
-ECMAScript modules](./no-esm.html).
+For more information about this see the section on [deployment]
 
 ### `--typescript`
 
@@ -71,3 +76,9 @@ When post-processing the `.wasm` binary, do not demangle Rust symbols in the
 
 When post-processing the `.wasm` binary, do not strip DWARF debug info custom
 sections.
+
+### `--browser`
+
+When generating bundler-compatible code (see the section on [deployment]) this
+indicates that the bundled code is always intended to go into a browser so a few
+checks for Node.js can be elided.