fix(dev): version-safe Next dev launcher — quick-start on all supported Node - #72
Merged
Conversation
… new Node
`pnpm --filter composer dev` (and `pnpm dev` for the studio) died with exit 9
on Node 22.0–22.3: the scripts inlined NODE_OPTIONS=--localstorage-file,
which only EXISTS from Node 22.4 — older allowed-by-engines Nodes reject it
("not allowed in NODE_OPTIONS") before Next starts. Reproduced byte-for-byte
on a real v22.0.0 binary. The prior clean-checkout verification missed it
because "clean" covered files, not the machine's Node (v25, where the flag
is valid).
The flag is load-bearing where it exists — Node ≥ 25's stub server-side
localStorage global crashes Next dev SSR without it (CONTRIBUTING said
"don't remove it") — so the fix keeps the protection and removes the bomb:
each app's dev now goes through scripts/next-dev.mjs, which probes
process.allowedNodeEnvironmentFlags and adds --localstorage-file only where
this Node permits it. The hazard and the flag ship together, so every
supported Node gets exactly what it needs.
Verified:
- Node 22.0.0 (real binary): old inline form exits 9; via the launcher,
composer dev boots to HTTP 200.
- Node 22.4.0: flag allowed (boundary bracketed empirically).
- Node 25.2.1, CLEAN worktree: `pnpm install` + the documented
`pnpm --filter composer dev` → HTTP 200, with the SSR-protection branch
engaged; agent boots independently on :8787; web twin boots on :3000.
- Regression guard (5 unit tests, fail-first proven: the no-inline-flag
assertion fails on the old package.json): no package script may hardcode
the flag; env builder branches correctly on old/new Node and preserves
caller NODE_OPTIONS. Composer units 24/24.
CONTRIBUTING troubleshooting updated to point at the launcher. README needs
no change — the documented command now works on everything engines allows.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
dspack-studio-composer | 3f315f6 | Aug 10 2026, 05:41 PM |
There was a problem hiding this comment.
Pull request overview
This PR fixes the documented dev quick-start failing on Node 22.0–22.3 by routing Next dev through a version-/flag-aware launcher that only applies --localstorage-file when the running Node allows it, preserving the SSR protection needed on Node ≥ 25 while keeping Node ≥ 22 compatible.
Changes:
- Replace inlined
NODE_OPTIONS=--localstorage-file=...in app dev scripts with ascripts/next-dev.mjslauncher that probesprocess.allowedNodeEnvironmentFlags. - Add a Vitest regression suite to prevent re-inlining the flag in package scripts and validate launcher env behavior.
- Update CONTRIBUTING troubleshooting guidance to document the launcher and the Node 22.4 boundary.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| CONTRIBUTING.md | Documents the new launcher behavior and why inlining the flag breaks Node < 22.4. |
| apps/web/scripts/next-dev.mjs | New web Next dev launcher that conditionally injects --localstorage-file via NODE_OPTIONS. |
| apps/web/package.json | Switches dev to invoke the new launcher instead of inlining NODE_OPTIONS. |
| apps/composer/scripts/next-dev.mjs | New composer Next dev launcher mirroring the web launcher behavior. |
| apps/composer/scripts/next-dev.test.mjs | Adds regression tests preventing re-inlining and validating conditional env injection. |
| apps/composer/package.json | Switches dev to invoke the new launcher instead of inlining NODE_OPTIONS. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| return { ...baseEnv, NODE_OPTIONS: prior ? `${prior} ${flag}` : flag }; | ||
| } | ||
|
|
||
| const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").at(-1)); |
| return { ...baseEnv, NODE_OPTIONS: prior ? `${prior} ${flag}` : flag }; | ||
| } | ||
|
|
||
| const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").at(-1)); |
| import { describe, expect, it } from "vitest"; | ||
| import { readFileSync } from "node:fs"; | ||
| import { fileURLToPath } from "node:url"; | ||
| import { webstorageEnv } from "./next-dev.mjs"; |
Comment on lines
+29
to
+32
| it("new Node (flag allowed): the SSR protection is applied", () => { | ||
| const env = webstorageEnv({}, new Set(["--localstorage-file"])); | ||
| expect(env.NODE_OPTIONS).toBe("--localstorage-file=/tmp/dspack-composer-dev-localstorage"); | ||
| }); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The documented quick-start (
pnpm --filter composer dev) failed with exit 9 on Node 22.0–22.3: the dev scripts inlinedNODE_OPTIONS=--localstorage-file, a flag that only exists from Node 22.4 — whileenginesallows>=22. Reproduced on a real v22.0.0 binary; boundary bracketed at v22.4.0. The flag is load-bearing on Node ≥ 25 (stub server-sidelocalStoragecrashes Next dev SSR without it), so instead of removing it, each app's dev now runs throughscripts/next-dev.mjs, which probesprocess.allowedNodeEnvironmentFlagsand applies the flag only where this Node supports it — the hazard and the flag ship together.Verified: Node 22.0.0 boots composer dev to HTTP 200 via the launcher (old form exits 9); clean-worktree
pnpm install+ documented command → 200 on v25 with the protection branch engaged; agent independent on :8787; web twin on :3000. 5-test regression guard (fail-first proven) forbids re-inlining the flag. Composer units 24/24; CONTRIBUTING updated; README unchanged (the command it documents now simply works).🤖 Generated with Claude Code