From c144f98957503f829d225e2e0fa8ff8074887bf3 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 13 Nov 2025 21:55:21 +0100 Subject: [PATCH 1/3] doc,src,lib: clarify experimental status of Web Storage support --- doc/api/cli.md | 27 +++++++++++++++++---------- doc/api/globals.md | 25 +++++++++++++++++++------ doc/node.1 | 4 ++-- lib/internal/process/pre_execution.js | 2 +- src/node_options.cc | 6 +++--- 5 files changed, 42 insertions(+), 22 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index eb72e6e4b396b4..fdd9f87f2ba9bc 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1745,10 +1745,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` @@ -1910,6 +1911,20 @@ added: v22.0.0 Disable exposition of {WebSocket} on the global scope. +### `--no-experimental-webstorage` + + + +> Stability: 1.2 - Release candidate. + +Disable [`Web Storage`][] support. + ### `--no-extra-info-on-fatal-exception` - -Disable [`Web Storage`][] support. - ### `--node-memory-debug` +> 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}. -> 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 index 72800cd364222b..540ce661a0d182 100644 --- 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 index 76ec7d821cb4cc..283ec72d388572 100644 --- 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 index 6f5475c3d9bd14..8dd186477c8875 100644 --- 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, From f3bc889f9a788d84d04f58cfcd3202eceaeb3a0e Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 14 Nov 2025 14:04:20 +0100 Subject: [PATCH 2/3] Update doc/api/globals.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: René --- doc/api/globals.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/api/globals.md b/doc/api/globals.md index 2d65700606effa..7e2b4026731208 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -647,9 +647,14 @@ added: v22.4.0 changes: - version: v25.2.0 pr-url: https://github.com/nodejs/node/pull/60351 - description: As specified by the Web Storage specification, accessing this - global without providing `--localstorage-file` throws a - `DOMException`. + description: Accessing the `localStorage` global without providing + `--localstorage-file` now throws a `DOMException`, for + compliance with the Web Storage specification. + - 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. From be312f1d8221ea95cdef2e96ef3e3bb40c3691f6 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 14 Nov 2025 14:05:24 +0100 Subject: [PATCH 3/3] Update doc/api/globals.md --- doc/api/globals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/globals.md b/doc/api/globals.md index 7e2b4026731208..fee0236de5004c 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -645,7 +645,7 @@ A browser-compatible implementation of {Headers}.