doc,src,lib: clarify experimental status of Web Storage support

aduh95 · aduh95 · commit ca878bc90e02 · 2025-11-16T20:47:29.000+01:00
PR-URL: #60708 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -1741,10 +1741,11 @@ surface on other platforms, but the performance impact may be severe.
 added: v22.4.0
 -->
 
+> Stability: 1.2 - Release candidate.
+
 The file used to store `localStorage` data. If the file does not exist, it is
 created the first time `localStorage` is accessed. The same file may be shared
-between multiple Node.js processes concurrently. This flag is a no-op if
-Node.js is started with the `--no-webstorage` (or `--no-experimental-webstorage`) flag.
+between multiple Node.js processes concurrently.
 
 ### `--max-http-header-size=size`
 
@@ -1906,6 +1907,20 @@ added: v22.0.0
 
 Disable exposition of {WebSocket} on the global scope.
 
+### `--no-experimental-webstorage`
+
+<!-- YAML
+added: v22.4.0
+changes:
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: The feature is now enabled by default.
+-->
+
+> Stability: 1.2 - Release candidate.
+
+Disable [`Web Storage`][] support.
+
 ### `--no-extra-info-on-fatal-exception`
 
 <!-- YAML
@@ -1973,14 +1988,6 @@ added: v6.0.0
 
 Silence all process warnings (including deprecations).
 
-### `--no-webstorage`
-
-<!-- YAML
-added: v25.0.0
--->
-
-Disable [`Web Storage`][] support.
-
 ### `--node-memory-debug`
 
 <!-- YAML
diff --git a/doc/api/globals.md b/doc/api/globals.md
@@ -644,13 +644,23 @@ A browser-compatible implementation of {Headers}.
 
 <!-- YAML
 added: v22.4.0
+changes:
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: When webstorage is enabled and `--localstorage-file` is not
+                 provided, accessing the `localStorage` global now returns an
+                 empty object.
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: This API is no longer behind `--experimental-webstorage` runtime flag.
 -->
 
+> Stability: 1.2 - Release candidate. Disable this API with [`--no-experimental-webstorage`][].
+
 A browser-compatible implementation of [`localStorage`][]. Data is stored
 unencrypted in the file specified by the [`--localstorage-file`][] CLI flag.
 The maximum amount of data that can be stored is 10 MB.
 Any modification of this data outside of the Web Storage API is not supported.
-Disable this API with the [`--no-webstorage`][] (or its alias `--no-experimental-webstorage`) CLI flag.
 `localStorage` data is not stored per user or per request when used in the context
 of a server, it is shared across all users and requests.
 
@@ -1073,9 +1083,13 @@ A browser-compatible implementation of {Request}.
 
 <!-- YAML
 added: v22.4.0
+changes:
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: This API is no longer behind `--experimental-webstorage` runtime flag.
 -->
 
-> Stability: 1.0 - Early development.
+> Stability: 1.2 - Release candidate. Disable this API with [`--no-experimental-webstorage`][].
 
 A browser-compatible implementation of [`sessionStorage`][]. Data is stored in
 memory, with a storage quota of 10 MB. `sessionStorage` data persists only within
@@ -1111,10 +1125,9 @@ added: v0.0.1
 added: v22.4.0
 -->
 
-> Stability: 1.0 - Early development.
+> Stability: 1.2 - Release candidate. Disable this API with [`--no-experimental-webstorage`][].
 
-A browser-compatible implementation of {Storage}. Disable this API with the
-[`--no-webstorage`][] (or its alias `--no-experimental-webstorage`) CLI flag.
+A browser-compatible implementation of {Storage}.
 
 ## `structuredClone(value[, options])`
 
@@ -1328,7 +1341,7 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
 [`--localstorage-file`]: cli.md#--localstorage-filefile
 [`--no-experimental-global-navigator`]: cli.md#--no-experimental-global-navigator
 [`--no-experimental-websocket`]: cli.md#--no-experimental-websocket
-[`--no-webstorage`]: cli.md#--no-webstorage
+[`--no-experimental-webstorage`]: cli.md#--no-experimental-webstorage
 [`ByteLengthQueuingStrategy`]: webstreams.md#class-bytelengthqueuingstrategy
 [`CompressionStream`]: webstreams.md#class-compressionstream
 [`CountQueuingStrategy`]: webstreams.md#class-countqueuingstrategy
diff --git a/doc/node.1 b/doc/node.1
@@ -207,8 +207,8 @@ Enable experimental support for the EventSource Web API.
 .It Fl -no-experimental-websocket
 Disable experimental support for the WebSocket API.
 .
-.It Fl -no-webstorage
-Disable webstorage.
+.It Fl -no-experimental-webstorage
+Disable experimental support for the Web Storage API.
 .
 .It Fl -no-experimental-repl-await
 Disable top-level await keyword support in REPL.
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
@@ -398,7 +398,7 @@ function setupQuic() {
 
 function setupWebStorage() {
   if (getEmbedderOptions().noBrowserGlobals ||
-      !getOptionValue('--webstorage')) {
+      !getOptionValue('--experimental-webstorage')) {
     return;
   }
 
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -567,12 +567,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             NoOp{},
 #endif
             kAllowedInEnvvar);
-  AddOption("--webstorage",
-            "Web Storage API",
+  AddOption("--experimental-webstorage",
+            "experimental Web Storage API",
             &EnvironmentOptions::webstorage,
             kAllowedInEnvvar,
             true);
-  AddAlias("--experimental-webstorage", "--webstorage");
+  AddAlias("--webstorage", "--experimental-webstorage");
   AddOption("--localstorage-file",
             "file used to persist localStorage data",
             &EnvironmentOptions::localstorage_file,

Original file line number	Diff line number	Diff line change
`@@ -207,8 +207,8 @@ Enable experimental support for the EventSource Web API.`
`207`	`207`	`.It Fl -no-experimental-websocket`
`208`	`208`	`Disable experimental support for the WebSocket API.`
`209`	`209`	`.`
`210`		`-.It Fl -no-webstorage`
`211`		`-Disable webstorage.`
	`210`	`+.It Fl -no-experimental-webstorage`
	`211`	`+Disable experimental support for the Web Storage API.`
`212`	`212`	`.`
`213`	`213`	`.It Fl -no-experimental-repl-await`
`214`	`214`	`Disable top-level await keyword support in REPL.`
Original file line number	Diff line number	Diff line change
`@@ -398,7 +398,7 @@ function setupQuic() {`
`398`	`398`
`399`	`399`	`function setupWebStorage() {`
`400`	`400`	`if (getEmbedderOptions().noBrowserGlobals \|\|`
`401`		`- !getOptionValue('--webstorage')) {`
	`401`	`+ !getOptionValue('--experimental-webstorage')) {`
`402`	`402`	`return;`
`403`	`403`	`}`
`404`	`404`