Rename feature js -> wasm_js and remove auto opt-in

.github/workflows/build.yml

@@ -142,8 +142,8 @@ jobs:
           { description: WasmV1, target: wasm32v1-none },
         ]
         feature: [
-          { description: no_std, feature: "--features js", build-std: "core,alloc", std: false },
-          { feature: "--features js,std", build-std: "panic_abort,std", std: true },
+          { description: no_std, feature: "--features wasm_js", build-std: "core,alloc", std: false },
+          { feature: "--features wasm_js,std", build-std: "panic_abort,std", std: true },
         ]
         atomic: [
           { flags: "" },

.github/workflows/tests.yml

@@ -237,14 +237,14 @@ jobs:
           - {
               description: Web,
               version: stable,
-              args: '--features=std,js',
+              args: '--features=std,wasm_js',
             }
           - {
               description: Web with Atomics,
               version: nightly,
               components: rust-src,
               flags: '-Dwarnings --cfg getrandom_backend="wasm_js" -Ctarget-feature=+atomics,+bulk-memory',
-              args: '--features=std,js -Zbuild-std=panic_abort,std',
+              args: '--features=std,wasm_js -Zbuild-std=panic_abort,std',
             }
     steps:
       - uses: actions/checkout@v4

.github/workflows/workspace.yml

@@ -48,11 +48,11 @@ jobs:
     - name: Web WASM (wasm_js.rs)
       env:
         RUSTFLAGS: -Dwarnings --cfg getrandom_backend="wasm_js"
-      run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features js
+      run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features wasm_js
     - name: Web WASM with atomics (wasm_js.rs)
       env:
         RUSTFLAGS: -Dwarnings --cfg getrandom_backend="wasm_js" -Ctarget-feature=+atomics,+bulk-memory
-      run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features js
+      run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features wasm_js
     - name: Linux (linux_android.rs)
       env:
         RUSTFLAGS: -Dwarnings --cfg getrandom_backend="linux_getrandom"

Cargo.toml

@@ -19,9 +19,9 @@ std = []
 rustc-dep-of-std = ["dep:compiler_builtins", "dep:core"]
 
 # Optional backend: wasm_js
-# This flag enables the backend and uses it by default on wasm32 with unknown OS.
-# The backend may still be overridden by setting getrandom_backend.
-js = ["dep:wasm-bindgen", "dep:js-sys"]
+# This flag enables the backend but does not select it. To use the backend, use
+# this flag *and* set getrandom_backend=wasm_js (see README).
+wasm_js = ["dep:wasm-bindgen", "dep:js-sys"]
 
 [dependencies]
 cfg-if = "1"

README.md

@@ -82,7 +82,7 @@ of randomness based on their specific needs:
 | `linux_getrandom` | Linux, Android       | `*‑linux‑*`              | [`getrandom`][1] system call (without `/dev/urandom` fallback). Bumps minimum supported Linux kernel version to 3.17 and Android API level to 23 (Marshmallow).
 | `rdrand`          | x86, x86-64          | `x86_64-*`, `i686-*`     | [`RDRAND`] instruction
 | `rndr`            | AArch64              | `aarch64-*`              | [`RNDR`] register
-| `wasm_js`         | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]. Requires feature `js`.
+| `wasm_js`         | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]. Requires feature `wasm_js` ([see below](#webassembly-support)).
 | `custom`          | All targets          | `*`                      | User-provided custom implementation (see [custom backend])
 
 Opt-in backends can be enabled using the `getrandom_backend` configuration flag.
@@ -112,19 +112,19 @@ the `wasm32-unknown-unknown` target (i.e. the target used by `wasm-pack`)
 is not automatically supported since, from the target name alone, we cannot deduce
 which JavaScript interface should be used (or if JavaScript is available at all).
 
-Instead, *if the `js` feature is enabled*, this crate will assume
-that you are building for an environment containing JavaScript, and will
-call the appropriate Web Crypto methods [described above](#opt-in-backends) using
-the [`wasm-bindgen`] toolchain (with or without using `getrandom_backend=wasm_js`).
-Both web browser (main window and Web Workers)
-and Node.js (v19 or later) environments are supported.
+To enable `getrandom`'s functionality on `wasm32-unknown-unknown` using the Web
+Crypto methods [described above](#opt-in-backends) via [`wasm-bindgen`], do
+*both* of the following:
 
-To enable the `wasm_js` backend, you can add the following lines to your
-project's `.cargo/config.toml` file:
-```toml
-[dependencies]
-getrandom = { version = "0.3", features = ["js"] }
-```
+-   Use the `wasm_js` feature flag, i.e.
+    `getrandom = { version = "0.3", features = ["wasm_js"] }`.
+    On its own, this only makes the backend available. (As a side effect this
+    will make your `Cargo.lock` significantly larger if you are not already
+    using [`wasm-bindgen`], but otherwise enabling this feature is harmless.)
+-   Set `RUSTFLAGS='--cfg getrandom_backend="wasm_js"'` ([see above](#opt-in-backends)).
+
+This backend supports both web browsers (main window and Web Workers)
+and Node.js (v19 or later) environments.
 
 ### Custom backend
 

src/backends.rs

@@ -19,7 +19,7 @@ cfg_if! {
     } else if #[cfg(getrandom_backend = "rndr")] {
         mod rndr;
         pub use rndr::*;
-    } else if #[cfg(all(feature = "js", getrandom_backend = "wasm_js"))] {
+    } else if #[cfg(all(feature = "wasm_js", getrandom_backend = "wasm_js"))] {
         mod wasm_js;
         pub use wasm_js::*;
     } else if #[cfg(target_os = "espidf")] {
@@ -127,18 +127,6 @@ cfg_if! {
                 );
             }
         }
-    } else if #[cfg(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none")))] {
-        cfg_if! {
-            if #[cfg(feature = "js")] {
-                mod wasm_js;
-                pub use wasm_js::*;
-            } else {
-                compile_error!("the wasm32-unknown-unknown targets are not supported \
-                                by default, you may need to enable the \"js\" \
-                                feature flag. For more information see: \
-                                https://docs.rs/getrandom/#webassembly-support");
-            }
-        }
     } else if #[cfg(target_os = "hermit")] {
         mod hermit;
         pub use hermit::*;
@@ -157,6 +145,14 @@ cfg_if! {
     } else if #[cfg(all(target_arch = "x86_64", target_env = "sgx"))] {
         mod rdrand;
         pub use rdrand::*;
+    } else if #[cfg(all(
+        target_arch = "wasm32",
+        any(target_os = "unknown", target_os = "none")
+    ))] {
+        compile_error!("the wasm32-unknown-unknown targets are not supported \
+                        by default, you may need to enable the \"wasm_js\" \
+                        configuration flag. For more information see: \
+                        https://docs.rs/getrandom/#webassembly-support");
     } else {
         compile_error!("target is not supported. You may need to define \
                         a custom backend see: \

src/error.rs

@@ -116,7 +116,7 @@ impl Error {
             Error::IOS_RANDOM_GEN => "SecRandomCopyBytes: iOS Security framework failure",
             #[cfg(all(windows, target_vendor = "win7"))]
             Error::WINDOWS_RTL_GEN_RANDOM => "RtlGenRandom: Windows system function failure",
-            #[cfg(all(feature = "js", getrandom_backend = "wasm_js"))]
+            #[cfg(all(feature = "wasm_js", getrandom_backend = "wasm_js"))]
             Error::WEB_CRYPTO => "Web Crypto API is unavailable",
             #[cfg(target_os = "vxworks")]
             Error::VXWORKS_RAND_SECURE => "randSecure: VxWorks RNG module is not initialized",

tests/mod.rs

@@ -1,7 +1,7 @@
 use core::mem::MaybeUninit;
 use getrandom::{fill, fill_uninit};
 
-#[cfg(all(feature = "js", target_arch = "wasm32", target_os = "unknown"))]
+#[cfg(all(feature = "wasm_js", target_arch = "wasm32", target_os = "unknown"))]
 use wasm_bindgen_test::wasm_bindgen_test as test;
 
 #[test]