@typescript/vfs emits an ExperimentalWarning on Node 26 during localStorage feature detection

Bắt đầu trong packages/typescript-vfs/src/index.ts và tái hiện cảnh báo lúc import với Node 26, tập trung vào việc phát hiện tính năng localStorage ở cấp cao nhất. Xác minh rằng thay đổi đã hoàn tất sẽ tránh được cảnh báo trong Node thuần, đồng thời vẫn duy trì việc phát hiện cho môi trường trình duyệt và các môi trường tương tự Electron; issue ghi chú rằng một PR đã được gửi đến.

Summary

Importing @typescript/vfs on Node 26 prints:

(node:39835) ExperimentalWarning: localStorage is not available because --localstorage-file was not provided.
(Use `node --trace-warnings ...` to show where the warning was created)

It fires at module evaluation, before any API of the package is called.

Cause

packages/typescript-vfs/src/index.ts runs this at top level:

let hasLocalStorage = false
try {
  hasLocalStorage = typeof localStorage !== `undefined`
} catch (error) { }

On Node 26, globalThis.localStorage is an accessor. Reading it — including via typeof — invokes the getter, which emits the ExperimentalWarning and then returns undefined when --localstorage-file was not passed.

So the feature detect reaches the correct conclusion (hasLocalStorage === false) having already printed a warning as a side effect of asking the question.

The existing try/catch does not help. It anticipates a global that throws; Node 26's does not throw, it warns and returns undefined. The guard is bypassed rather than triggered.

This is distinct from #3449 / #3450, which fixed the crash on Node 25 (localStorage.getItem is not a function). That fix is still correct and still needed; the warning is a separate side effect of the probe itself.

Verified on

• Node v26.8.1 (also reproduces on v26.7.0)
• @typescript/vfs@1.6.4

Minimal reproduction, no bundler involved:

$ node --version
v26.8.1

$ node -e 'console.log("typeof =", typeof localStorage)'
typeof = undefined
(node:2971) ExperimentalWarning: localStorage is not available because --localstorage-file was not provided.
(Use `node --trace-warnings ...` to show where the warning was created)

Traced to the exact line:

$ node --trace-warnings -e "require('@typescript/vfs/dist/vfs.cjs.development.js');"
(node:39835) ExperimentalWarning: localStorage is not available ...
    at Object.get (node:internal/webstorage:42:21)
    at get (node:internal/process/pre_execution:452:58)
    at Object.<anonymous> (.../@typescript/vfs/dist/vfs.cjs.development.js:17:3)

A named static import reaches it too — the line is top-level module code, so which bindings a consumer destructures is irrelevant:

import { createSystem, createVirtualTypeScriptEnvironment } from "@typescript/vfs"
// still warns at evaluation

Blast radius

Wider than this package's direct dependents. twoslash imports it statically at dist/core.mjs:1, so every Twoslash consumer on Node 26 gets the warning whether or not they use @typescript/vfs themselves — including Shiki's @shikijs/twoslash and, through it, docs pipelines that never touch a virtual filesystem knowingly.

Impact is cosmetic — one warning line per Node process, no behaviour change — but it is unsuppressable from the consumer side without a blanket process.on("warning") filter, which is where warnings you actually wanted go to die.

Suggested fix

Don't probe the accessor in Node at all. The value is only ever used to look up a DEBUG key, and in a Node process process.env.DEBUG is the only reachable way to set it anyway:

const hasProcess = typeof process !== `undefined`
const isBareNodeProcess =
  hasProcess && typeof process.versions?.node === `string` && !(`window` in globalThis)

let hasLocalStorage = false
if (!isBareNodeProcess) {
  try {
    hasLocalStorage = typeof localStorage !== `undefined` && typeof localStorage.getItem === `function`
  } catch (error) { }
}

'window' in globalThis checks for the property without invoking any getter, so browsers and DOM-bearing hosts that also expose process (Electron renderers) keep the existing behaviour, while bare Node skips the probe.

Alternatives considered and rejected:

• Object.getOwnPropertyDescriptor(globalThis, "localStorage") avoids the getter, but in browsers localStorage lives on Window.prototype rather than as an own property of globalThis, so the descriptor comes back undefined and browser detection breaks.
• Gating on hasProcess alone would regress Electron renderers, which have both process and a real localStorage.

PR incoming.

Aside

packages/typescript-vfs/package.json has repository.directory set to packages/create-typescript-playground-plugin, which looks like a copy/paste slip — the source is packages/typescript-vfs. Happy to fold that into the same PR or leave it alone, whichever you prefer.