src: unflag --experimental-webstorage by default

danielmbrasil · web-flow · commit 3312e4e94679 · 2025-09-25T11:59:58.000Z
PR-URL: #57666 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Edy Silva <edigleyssonsilva@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/benchmark/webstorage/getItem.js b/benchmark/webstorage/getItem.js
@@ -12,7 +12,7 @@ function nextLocalStorage() {
 }
 
 const options = {
-  flags: ['--experimental-webstorage', `--localstorage-file=${nextLocalStorage()}`],
+  flags: [`--localstorage-file=${nextLocalStorage()}`],
 };
 
 const bench = common.createBenchmark(main, {
diff --git a/benchmark/webstorage/removeItem.js b/benchmark/webstorage/removeItem.js
@@ -12,7 +12,7 @@ function nextLocalStorage() {
 }
 
 const options = {
-  flags: ['--experimental-webstorage', `--localstorage-file=${nextLocalStorage()}`],
+  flags: [`--localstorage-file=${nextLocalStorage()}`],
 };
 
 const bench = common.createBenchmark(main, {
diff --git a/benchmark/webstorage/setItem.js b/benchmark/webstorage/setItem.js
@@ -12,7 +12,7 @@ function nextLocalStorage() {
 }
 
 const options = {
-  flags: ['--experimental-webstorage', `--localstorage-file=${nextLocalStorage()}`],
+  flags: [`--localstorage-file=${nextLocalStorage()}`],
 };
 
 const bench = common.createBenchmark(main, {
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -1305,14 +1305,6 @@ changes:
 
 Enable experimental WebAssembly System Interface (WASI) support.
 
-### `--experimental-webstorage`
-
-<!-- YAML
-added: v22.4.0
--->
-
-Enable experimental [`Web Storage`][] support.
-
 ### `--experimental-worker-inspection`
 
 <!-- YAML
@@ -1753,8 +1745,8 @@ added: v22.4.0
 
 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 unless
-Node.js is started with the `--experimental-webstorage` flag.
+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.
 
 ### `--max-http-header-size=size`
 
@@ -1979,6 +1971,14 @@ added: v6.0.0
 
 Silence all process warnings (including deprecations).
 
+### `--no-webstorage`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Disable [`Web Storage`][] support.
+
 ### `--node-memory-debug`
 
 <!-- YAML
@@ -3503,7 +3503,6 @@ one is included in the list below.
 * `--experimental-transform-types`
 * `--experimental-vm-modules`
 * `--experimental-wasi-unstable-preview1`
-* `--experimental-webstorage`
 * `--force-context-aware`
 * `--force-fips`
 * `--force-node-api-uncaught-exceptions-policy`
@@ -3537,11 +3536,13 @@ one is included in the list below.
 * `--no-experimental-sqlite`
 * `--no-experimental-strip-types`
 * `--no-experimental-websocket`
+* `--no-experimental-webstorage`
 * `--no-extra-info-on-fatal-exception`
 * `--no-force-async-hooks-checks`
 * `--no-global-search-paths`
 * `--no-network-family-autoselection`
 * `--no-warnings`
+* `--no-webstorage`
 * `--node-memory-debug`
 * `--openssl-config`
 * `--openssl-legacy-provider`
diff --git a/doc/api/globals.md b/doc/api/globals.md
@@ -640,13 +640,11 @@ A browser-compatible implementation of {Headers}.
 added: v22.4.0
 -->
 
-> Stability: 1.0 - Early development.
-
 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.
-Enable this API with the [`--experimental-webstorage`][] CLI flag.
+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.
 
@@ -1108,9 +1106,10 @@ added: v22.4.0
 -->
 
 > Stability: 1.0 - Early development. Enable this API with the
-> [`--experimental-webstorage`][] CLI flag.
+> \[`--experimental-webstorage`]\[] CLI flag.
 
-A browser-compatible implementation of {Storage}.
+A browser-compatible implementation of {Storage}. Disable this API with the
+[`--no-webstorage`][] (or its alias `--no-experimental-webstorage`) CLI flag.
 
 ## `structuredClone(value[, options])`
 
@@ -1321,10 +1320,10 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
 [RFC 5646]: https://www.rfc-editor.org/rfc/rfc5646.txt
 [Web Crypto API]: webcrypto.md
 [`--experimental-eventsource`]: cli.md#--experimental-eventsource
-[`--experimental-webstorage`]: cli.md#--experimental-webstorage
 [`--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
 [`ByteLengthQueuingStrategy`]: webstreams.md#class-bytelengthqueuingstrategy
 [`CompressionStream`]: webstreams.md#class-compressionstream
 [`CountQueuingStrategy`]: webstreams.md#class-countqueuingstrategy
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
@@ -189,9 +189,6 @@
         "experimental-websocket": {
           "type": "boolean"
         },
-        "experimental-webstorage": {
-          "type": "boolean"
-        },
         "extra-info-on-fatal-exception": {
           "type": "boolean"
         },
@@ -597,6 +594,9 @@
         "watch-preserve-output": {
           "type": "boolean"
         },
+        "webstorage": {
+          "type": "boolean"
+        },
         "zero-fill-buffers": {
           "type": "boolean"
         }
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 -experimental-webstorage
-Enable experimental support for the Web Storage API.
+.It Fl -no-webstorage
+Disable webstorage.
 .
 .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
@@ -365,7 +365,7 @@ function setupQuic() {
 
 function setupWebStorage() {
   if (getEmbedderOptions().noBrowserGlobals ||
-      !getOptionValue('--experimental-webstorage')) {
+      !getOptionValue('--webstorage')) {
     return;
   }
 
diff --git a/lib/internal/webstorage.js b/lib/internal/webstorage.js
@@ -1,16 +1,13 @@
 'use strict';
 const {
   ObjectDefineProperties,
+  Proxy,
 } = primordials;
-const { ERR_INVALID_ARG_VALUE } = require('internal/errors').codes;
 const { getOptionValue } = require('internal/options');
-const { emitExperimentalWarning } = require('internal/util');
 const { kConstructorKey, Storage } = internalBinding('webstorage');
 const { getValidatedPath } = require('internal/fs/utils');
 const kInMemoryPath = ':memory:';
 
-emitExperimentalWarning('Web Storage');
-
 module.exports = { Storage };
 
 let lazyLocalStorage;
@@ -27,12 +24,31 @@ ObjectDefineProperties(module.exports, {
         const location = getOptionValue('--localstorage-file');
 
         if (location === '') {
-          throw new ERR_INVALID_ARG_VALUE('--localstorage-file',
-                                          location,
-                                          'is an invalid localStorage location');
-        }
+          let warningEmitted = false;
+          const handler = {
+            __proto__: null,
+            get(target, prop) {
+              if (!warningEmitted) {
+                process.emitWarning('`--localstorage-file` was provided without a valid path');
+                warningEmitted = true;
+              }
+
+              return undefined;
+            },
+            set(target, prop, value) {
+              if (!warningEmitted) {
+                process.emitWarning('`--localstorage-file` was provided without a valid path');
+                warningEmitted = true;
+              }
 
-        lazyLocalStorage = new Storage(kConstructorKey, getValidatedPath(location));
+              return false;
+            },
+          };
+
+          lazyLocalStorage = new Proxy({}, handler);
+        } else {
+          lazyLocalStorage = new Storage(kConstructorKey, getValidatedPath(location));
+        }
       }
 
       return lazyLocalStorage;
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -559,10 +559,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             NoOp{},
 #endif
             kAllowedInEnvvar);
-  AddOption("--experimental-webstorage",
-            "experimental Web Storage API",
-            &EnvironmentOptions::experimental_webstorage,
-            kAllowedInEnvvar);
+  AddOption("--webstorage",
+            "Web Storage API",
+            &EnvironmentOptions::webstorage,
+            kAllowedInEnvvar,
+            true);
+  AddAlias("--experimental-webstorage", "--webstorage");
   AddOption("--localstorage-file",
             "file used to persist localStorage data",
             &EnvironmentOptions::localstorage_file,
diff --git a/src/node_options.h b/src/node_options.h
@@ -127,7 +127,7 @@ class EnvironmentOptions : public Options {
   bool experimental_fetch = true;
   bool experimental_websocket = true;
   bool experimental_sqlite = true;
-  bool experimental_webstorage = false;
+  bool webstorage = true;
 #ifndef OPENSSL_NO_QUIC
   bool experimental_quic = false;
 #endif
diff --git a/test/parallel/test-global.js b/test/parallel/test-global.js
@@ -59,6 +59,8 @@ for (const moduleName of builtinModules) {
     'fetch',
     'crypto',
     'navigator',
+    'localStorage',
+    'sessionStorage',
   ];
   assert.deepStrictEqual(new Set(Object.keys(globalThis)), new Set(expected));
   expected.forEach((value) => {
diff --git a/test/parallel/test-webstorage.js b/test/parallel/test-webstorage.js
@@ -1,4 +1,5 @@
 'use strict';
+
 const { skipIfSQLiteMissing, spawnPromisified } = require('../common');
 skipIfSQLiteMissing();
 const tmpdir = require('../common/tmpdir');
@@ -14,35 +15,9 @@ function nextLocalStorage() {
   return join(tmpdir.path, `${++cnt}.localstorage`);
 }
 
-test('disabled without --experimental-webstorage', async () => {
-  for (const api of ['Storage', 'localStorage', 'sessionStorage']) {
-    const cp = await spawnPromisified(process.execPath, ['-e', api]);
-
-    assert.strictEqual(cp.code, 1);
-    assert.strictEqual(cp.signal, null);
-    assert.strictEqual(cp.stdout, '');
-    assert(cp.stderr.includes(`ReferenceError: ${api} is not defined`));
-  }
-});
-
-test('emits a warning when used', async () => {
-  for (const api of ['Storage', 'localStorage', 'sessionStorage']) {
-    const cp = await spawnPromisified(process.execPath, [
-      '--experimental-webstorage',
-      '--localstorage-file', nextLocalStorage(),
-      '-e', api,
-    ]);
-
-    assert.strictEqual(cp.code, 0);
-    assert.strictEqual(cp.signal, null);
-    assert.strictEqual(cp.stdout, '');
-    assert.match(cp.stderr, /ExperimentalWarning: Web Storage/);
-  }
-});
-
 test('Storage instances cannot be created in userland', async () => {
   const cp = await spawnPromisified(process.execPath, [
-    '--experimental-webstorage', '-e', 'new globalThis.Storage()',
+    '-e', 'new globalThis.Storage()',
   ]);
 
   assert.strictEqual(cp.code, 1);
@@ -53,33 +28,30 @@ test('Storage instances cannot be created in userland', async () => {
 
 test('sessionStorage is not persisted', async () => {
   let cp = await spawnPromisified(process.execPath, [
-    '--experimental-webstorage', '-pe', 'sessionStorage.foo = "barbaz"',
+    '-pe', 'sessionStorage.foo = "barbaz"',
   ]);
   assert.strictEqual(cp.code, 0);
   assert.match(cp.stdout, /barbaz/);
 
   cp = await spawnPromisified(process.execPath, [
-    '--experimental-webstorage', '-pe', 'sessionStorage.foo',
+    '-pe', 'sessionStorage.foo',
   ]);
   assert.strictEqual(cp.code, 0);
   assert.match(cp.stdout, /undefined/);
   assert.strictEqual((await readdir(tmpdir.path)).length, 0);
 });
 
-test('localStorage throws without --localstorage-file ', async () => {
+test('localStorage emits a warning when used without --localstorage-file ', async () => {
   const cp = await spawnPromisified(process.execPath, [
-    '--experimental-webstorage',
-    '-pe', 'localStorage === globalThis.localStorage',
+    '-pe', 'localStorage.length',
   ]);
-  assert.strictEqual(cp.code, 1);
+  assert.strictEqual(cp.code, 0);
   assert.strictEqual(cp.signal, null);
-  assert.strictEqual(cp.stdout, '');
-  assert.match(cp.stderr, /The argument '--localstorage-file' is an invalid localStorage location/);
+  assert.match(cp.stderr, /Warning: `--localstorage-file` was provided without a valid path/);
 });
 
 test('localStorage is not persisted if it is unused', async () => {
   const cp = await spawnPromisified(process.execPath, [
-    '--experimental-webstorage',
     '--localstorage-file', nextLocalStorage(),
     '-pe', 'localStorage === globalThis.localStorage',
   ]);
@@ -91,7 +63,6 @@ test('localStorage is not persisted if it is unused', async () => {
 test('localStorage is persisted if it is used', async () => {
   const localStorageFile = nextLocalStorage();
   let cp = await spawnPromisified(process.execPath, [
-    '--experimental-webstorage',
     '--localstorage-file', localStorageFile,
     '-pe', 'localStorage.foo = "barbaz"',
   ]);
@@ -102,7 +73,6 @@ test('localStorage is persisted if it is used', async () => {
   assert.match(entries[0], /\d+\.localstorage/);
 
   cp = await spawnPromisified(process.execPath, [
-    '--experimental-webstorage',
     '--localstorage-file', localStorageFile,
     '-pe', 'localStorage.foo',
   ]);
@@ -117,7 +87,6 @@ describe('webstorage quota for localStorage and sessionStorage', () => {
   test('localStorage can store and retrieve a max of 10 MB quota', async () => {
     const localStorageFile = nextLocalStorage();
     const cp = await spawnPromisified(process.execPath, [
-      '--experimental-webstorage',
       '--localstorage-file', localStorageFile,
       // Each character is 2 bytes
       '-pe', `
@@ -133,7 +102,6 @@ describe('webstorage quota for localStorage and sessionStorage', () => {
 
   test('sessionStorage can store a max of 10 MB quota', async () => {
     const cp = await spawnPromisified(process.execPath, [
-      '--experimental-webstorage',
       // Each character is 2 bytes
       '-pe', `sessionStorage['a'.repeat(${MAX_STORAGE_SIZE} / 2)] = '';
       console.error('filled');
@@ -145,3 +113,20 @@ describe('webstorage quota for localStorage and sessionStorage', () => {
     assert.match(cp.stderr, /QuotaExceededError/);
   });
 });
+
+test('disabled with --no-webstorage', async () => {
+  for (const api of ['Storage', 'localStorage', 'sessionStorage']) {
+    const cp = await spawnPromisified(process.execPath, [
+      '--no-webstorage',
+      '--localstorage-file',
+      './test/fixtures/localstoragefile-global-test',
+      '-e',
+      api,
+    ]);
+
+    assert.strictEqual(cp.code, 1);
+    assert.strictEqual(cp.signal, null);
+    assert.strictEqual(cp.stdout, '');
+    assert(cp.stderr.includes(`ReferenceError: ${api} is not defined`));
+  }
+});
diff --git a/test/wpt/test-webstorage.js b/test/wpt/test-webstorage.js

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ function nextLocalStorage() {`
`12`	`12`	`}`
`13`	`13`
`14`	`14`	`const options = {`
`15`		- flags: ['--experimental-webstorage', `--localstorage-file=${nextLocalStorage()}`],
	`15`	+ flags: [`--localstorage-file=${nextLocalStorage()}`],
`16`	`16`	`};`
`17`	`17`
`18`	`18`	`const bench = common.createBenchmark(main, {`
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 -experimental-webstorage`
`211`		`-Enable experimental support for the Web Storage API.`
	`210`	`+.It Fl -no-webstorage`
	`211`	`+Disable webstorage.`
`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
`@@ -365,7 +365,7 @@ function setupQuic() {`
`365`	`365`
`366`	`366`	`function setupWebStorage() {`
`367`	`367`	`if (getEmbedderOptions().noBrowserGlobals \|\|`
`368`		`- !getOptionValue('--experimental-webstorage')) {`
	`368`	`+ !getOptionValue('--webstorage')) {`
`369`	`369`	`return;`
`370`	`370`	`}`
`371`	`371`