Rename option and improve documentation

Author: lukaslihotzki

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

@@ -3148,7 +3148,7 @@ impl<'a> Context<'a> {
                 assert!(kind == AdapterJsImportKind::Normal);
                 assert!(!variadic);
                 assert_eq!(args.len(), 0);
-                if self.config.allow_links {
+                if self.config.split_linked_modules {
                     let base = match self.config.mode {
                         OutputMode::Web
                         | OutputMode::Bundler { .. }
@@ -3173,8 +3173,8 @@ impl<'a> Context<'a> {
                             "\"data:application/javascript,\" + encodeURIComponent(`{escaped}`)"
                         ))
                     } else {
-                        Err(anyhow!("wasm-bindgen needs to be invoked with `--allow-links`, because \"{}\" cannot be embedded.\n\
-                            See https://rustwasm.github.io/wasm-bindgen/reference/cli.html#--allow-links for details.", path))
+                        Err(anyhow!("wasm-bindgen needs to be invoked with `--split-linked-modules`, because \"{}\" cannot be embedded.\n\
+                            See https://rustwasm.github.io/wasm-bindgen/reference/cli.html#--split-linked-modules for details.", path))
                     }
                 }
             }

crates/cli-support/src/lib.rs

@@ -46,7 +46,7 @@ pub struct Bindgen {
     multi_value: bool,
     wasm_interface_types: bool,
     encode_into: EncodeInto,
-    allow_links: bool,
+    split_linked_modules: bool,
 }
 
 pub struct Output {
@@ -121,7 +121,7 @@ impl Bindgen {
             wasm_interface_types,
             encode_into: EncodeInto::Test,
             omit_default_module_path: true,
-            allow_links: true,
+            split_linked_modules: true,
         }
     }
 
@@ -306,8 +306,8 @@ impl Bindgen {
         self
     }
 
-    pub fn allow_links(&mut self, allow_links: bool) -> &mut Bindgen {
-        self.allow_links = allow_links;
+    pub fn split_linked_modules(&mut self, split_linked_modules: bool) -> &mut Bindgen {
+        self.split_linked_modules = split_linked_modules;
         self
     }
 

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

@@ -36,7 +36,8 @@ Options:
     --remove-name-section        Remove the debugging `name` section of the file
     --remove-producers-section   Remove the telemetry `producers` section
     --omit-default-module-path   Don't add WebAssembly fallback imports in generated JavaScript
-    --allow-links                Allow to use the `new URL('…', import.meta.url)` syntax
+    --split-linked-modules       Split linked modules out into their own files. Recommended if possible.
+                                 If a bundler is used, it needs to be set up accordingly.
     --encode-into MODE           Whether or not to use TextEncoder#encodeInto,
                                  valid values are [test, always, never]
     --nodejs                     Deprecated, use `--target nodejs`
@@ -45,6 +46,8 @@ Options:
     --weak-refs                  Enable usage of the JS weak references proposal
     --reference-types            Enable usage of WebAssembly reference types
     -V --version                 Print the version number of wasm-bindgen
+
+Additional documentation: https://rustwasm.github.io/wasm-bindgen/reference/cli.html
 ";
 
 #[derive(Debug, Deserialize)]
@@ -71,7 +74,7 @@ struct Args {
     flag_encode_into: Option<String>,
     flag_target: Option<String>,
     flag_omit_default_module_path: bool,
-    flag_allow_links: bool,
+    flag_split_linked_modules: bool,
     arg_input: Option<PathBuf>,
 }
 
@@ -126,7 +129,7 @@ fn rmain(args: &Args) -> Result<(), Error> {
         .typescript(typescript)
         .omit_imports(args.flag_omit_imports)
         .omit_default_module_path(args.flag_omit_default_module_path)
-        .allow_links(args.flag_allow_links);
+        .split_linked_modules(args.flag_split_linked_modules);
     if let Some(true) = args.flag_weak_refs {
         b.weak_refs(true);
     }

guide/src/reference/cli.md

@@ -105,12 +105,16 @@ about reference types](./reference-types.md).
 
 Don't add WebAssembly fallback imports in generated JavaScript.
 
-### `--allow-links`
+### `--split-linked-modules`
 
-Allow to use the `new URL('…', import.meta.url)` link syntax. This is safe with
-webpack 5 or no bundler at all.
+Controls whether wasm-bindgen will split linked modules out into their own files.
+Enabling this is recommended, because it allows lazy loading and setting a
+stricter Content Security Policy.
+
+wasm-bindgen uses the `new URL('…', import.meta.url)` syntax to link such split
+out files. This is directly supported when using webpack 5 or no bundler at all.
 
 For other bundlers, ensure they support the link syntax, possibly by enabling an
-extra plugin. Alternatively, configure the bundler to keep the link syntax as is
-and to copy all files in `snippets/` to the output directory preserving their
-paths.
+extra plugin. That's why this option is disabled by default. Alternatively,
+configure the bundler to keep the link syntax as is and to copy all files in
+`snippets/` to the output directory preserving their paths.