Dependency modernization: Node 24, Vite, and Storybook 10

[spaceninja]

Dependency modernization: Node 24, Vite, and Storybook 10

Our dependency backlog isn't a queue of independent updates — it's one blocked chain plus a set of genuinely independent upgrades. This issue records what's actually blocking what, and the PR sequence we're using to unwind it.

The core finding: webpack is a dead end for our Storybook

@storybook/html-webpack5 stops at 8.6.14 — there is no stable 9 or 10 release. Storybook 10 for HTML is Vite-only.

This inverts how we've been reading the backlog. The closed PRs for css-loader v7, style-loader v4, mini-css-extract-plugin v2, postcss-loader v8, babel-loader v10, and sass-loader v17 are not blocked work waiting on a webpack 5 upgrade. On the Vite path those packages are deleted, not upgraded. Roughly ten dependencies leave package.json entirely.

We should not spend effort upgrading to webpack 5.

Spike results

A full spike (Storybook 10.5.9 + Vite 8 + Twing 7) builds and renders real Twig output. Findings:

• The Twig source preview works, including syntax highlighting. This is the issue that killed [Review carefully] Update storybook monorepo to v6.5.16 #2006 — Storybook 10 exposes SyntaxHighlighter.registerLanguage, so registering the Twig Prism grammar is a supported hook rather than the fragile react-syntax-highlighter reach-in that broke between 6.5.9 and 6.5.16.
• Twing 7 still renders synchronously via createSynchronousEnvironment. Stories stay () => template(args) — no async migration needed.
• We must import twing/light. The full Twing build pulls in locutus → safe-buffer, which crashes under Vite (Cannot read properties of undefined (reading 'prototype')) because Vite does not polyfill Node builtins the way webpack 4 did. All 24 Twig filters our templates use were tested against light — no regressions.
• The Vite plugin is simpler than what it replaces. twing-loader + source-inputs-loader + val-loader + virtual-bundled-environment collapse into roughly 60 lines. The source preview no longer needs the brittle string-replace against twing-loader's generated return template.render(context); we own the render wrapper, so path and args are recorded directly.
• ~~The custom Sass glob importer must be rewritten to Sass's modern canonicalize/load API (~40 lines). It's shared with gulp-sass, so gulp-sass v6 moves at the same time.~~ Superseded: the importer was deleted, not rewritten. A modern importer owns a URL namespace — everything reached through it comes back to it to resolve, with no fallback to Sass's own loader — so expanding one glob made us responsible for reimplementing Sass's _partial and index lookup rules by hand. All 57 stylesheets are committed source files, so src/index.scss now lists them explicitly and neither Vite nor gulp-sass needs any Sass configuration. gulp-sass v6 still moved at the same time.

Main cost: all 84 .stories.mdx files must migrate to CSF3 + .mdx. Storybook 10 has no indexer for .stories.mdx at all (No matching indexer found). button.stories.mdx also uses webpack's !!raw-loader! syntax, which becomes ?raw.

Node is separately unblockable

Twing 3's only incompatibility with modern Node is util.isNullOrUndefined, removed in Node 22. With a small shim, both the full test suite and the existing Storybook 6.5 + webpack 4 build pass on Node 24. That decouples the Node upgrade — and roughly 20 rate-limited updates behind it — from the Storybook project.

PR sequence

Revised. The original list was a risk ordering, not a dependency chain — only the Node
bump actually unblocked anything. We reprioritised to take Storybook 10 + Vite early,
since it deletes a large part of the backlog rather than upgrading it. The remaining
items (4–6) are independent of each other and of the work already shipped, so they can
land in any order.

• 1. Node 16 → 24 — Upgrade CI and local development to Node 24 #2392. Shipped.
• 2. Storybook 10 + Vite + Twing 7 — Upgrade to Storybook 10 + Vite, and Twing 7 #2405. Shipped. Twing 7, a Vite Twig plugin,
  Storybook 6.5 → 10, React 17 → 19, gulp-sass 6, the 84-file MDX migration, and
  deletion of the webpack toolchain (~10 dependencies removed, not upgraded).
• 3. Library build — Upgrade the library build to Rollup 4 and TypeScript 5 #2406. Shipped. rollup 2→4, rollup-plugin-dts 6,
  @rollup/plugin-terser 1, @rollup/plugin-babel 7, @rollup/plugin-node-resolve 16,
  TypeScript 5. Touched neither Storybook nor Twig. Landing this first let Upgrade to Storybook 10 + Vite, and Twing 7 #2405
  drop the temporary @types/node override instead of carrying it.
• 4. Lint & format — prettier 3, eslint, stylelint 17 + configs, and
  eslint-plugin-mdx 3 (moved here from the Storybook PR — see below). Prettier 3
  reformats the repo, so it wants its own PR. Prettier 3 also unblocks restoring
  @whitespace/storybook-addon-html at v9.
• 5. Misc toolchain — jest 30, style-dictionary 5, cssnano 8, js-yaml 5,
  npm-run-all2 9, sass.
• 6. Remove Gulp — 282 lines across 5 tasks and 6 gulp packages, and
  it is thinner than it looks: build-tokens.js is a 5-line wrapper that shells out
  to npm run preprocess:tokens, and build-scripts.js is already plain Rollup API.
  Deliberately kept out of the Storybook PR to keep that reviewable.

Changes forced by the Storybook work

• @types/node is pinned to 20.19.9 via overrides. Resolved — never landed.
  Webpack 4's dependency tree was holding it at 12.20.6; removing webpack let it float to
  26.2.0, which TypeScript 4.9 could not parse (syntax errors in ffi.d.ts, and
  skipLibCheck does not suppress parse errors). Pinning was the cheaper option at the
  time, but Upgrade the library build to Rollup 4 and TypeScript 5 #2406 landed TypeScript 5.9 first, so Upgrade to Storybook 10 + Vite, and Twing 7 #2405 was rebased onto it and dropped
  the override. There is no overrides block in package.json on main.
• @babel/preset-typescript is now a direct dependency. babel.config.js used it,
  but it was only present transitively via the Storybook 6 packages.
• eslint-plugin-mdx 3 moved out of the Storybook PR. It was blocked because MDX 1
  allowed arbitrary top-level JS and .stories.mdx relied on it. Now that the 84 files
  are MDX 3, the upgrade should be straightforward, so it belongs with the lint work.
• src/**/*.stories.js is excluded from tsconfig. Converting MDX to JS brought
  250+ story functions under checkJs for the first time — 269 errors. Stories are demo
  code, are not published, and were not type-checked as MDX either, so excluding them
  preserves existing coverage rather than expanding the PR. Type-checking stories would
  be a real improvement, but it is its own piece of work.

The PR 5 split idea did not pan out

The earlier note suggested extracting CSF from MDX while still on Storybook 6, to split
the migration in two. Both halves of that turned out to be dead ends:

• Storybook's own mdx-to-csf codemod cannot read our files. It parses with MDX 3,
  which rejects MDX 1's top-level const declarations — the exact thing every one of
  our story files used. The Storybook 10 CLI has also dropped the codemod entirely; it
  only survives in @storybook/codemod@8. Worth recording so nobody retries this.
• Migrating the files therefore needed a purpose-written transformer, which was going to
  be the bulk of the work either way. Splitting would have added a throwaway
  intermediate state without reducing the total effort.

Addon decisions needed in PR 5

• storybook-addon-outline — flagged deprecated with no replacement; outlines are built into Storybook core now, so this can likely just be dropped.
• storybook-mobile and @whitespace/storybook-addon-html — already commented out in .storybook/main.js "until they are fixed upstream". Drop them, or restore at v9.
• @storybook/addon-essentials and @storybook/addon-postcss — both removed/obsolete in Storybook 10.
• @etchteam/storybook-addon-status — needs v8.

Housekeeping

We run both Renovate and Dependabot, which is generating duplicate PRs for the same upgrades (lodash in #2368 and postcss in #2373 both duplicated Renovate security PRs at older versions, which is why they conflicted). Renovate is also configured with :automergeMinor, but branch protection requires an approving review, so its automerge can never fire. Aligning these would keep the backlog from rebuilding.

Smaller items noticed along the way

• gulp-svgmin v4 emits a warning: You are trying to enable removeXMLNS which is not part of preset. The SVGO plugin config needs updating.
• package.json still declares engines.node: ">=12.16.3". This describes what consumers of the published package need, not our dev environment, so it deliberately wasn't changed in PR 1 — but it's stale and deserves its own decision.

Storybook 6 → 10 API moves (for reference)

Collected while doing the migration:

Storybook 6	Storybook 10
docs.transformSource	docs.source.transform
docs.inlineStories	docs.story.inline
docs.prepareForInline	not needed — the HTML renderer inlines natively
viewport.viewports	viewport.options
@storybook/client-api	storybook/preview-api
@storybook/addons	storybook/manager-api
@storybook/theming/create	storybook/theming/create
@storybook/addon-viewport	storybook/viewport
<Description>{markdown}	<Markdown>{markdown} — Description now takes of={}
<ArgsTable>	<Controls>
ReactSyntaxHighlighter.registerLanguage	SyntaxHighlighter.registerLanguage from storybook/internal/components
require.context	import.meta.glob
!!raw-loader!x	x?raw
@svgr/webpack inline loader	vite-plugin-svgr with ?react

Two Twing 7 changes worth knowing: the filesystem loader is built from an injected fs
rather than a path, and path namespaces now include the sigil (@cloudfour, not
cloudfour). Rendering can still be synchronous via createSynchronousEnvironment, so
story functions keep returning strings.

The browser build must import twing/light. The full build pulls in locutus, which
needs Node's Buffer; webpack 4 shimmed that automatically and Vite does not, so the
bundle dies on load. All 24 filters our templates use work in light.

[spaceninja]

PR 1 of the sequence is open: #2392 (Node 16 → 24).

[spaceninja]

Found while verifying PR #2392: @svgr/webpack v8 (merged in #2386) is incompatible with webpack 4 — it calls this.getOptions(), which only exists on webpack 5's loader context. All 48 icons fail to compile, and because webpack 4 downgrades a failed loader to a warning, CI stayed green while Design → Icons rendered blank.

Fix is up as #2395 (pin back to v5). Adding to the notes above: this is a second reason not to invest in webpack 5 — @svgr/webpack is dropped entirely on the Vite path.

[spaceninja]

Reordered the plan above. To be explicit about what changed and why:

Nothing is invalidated. The original numbering read like a dependency chain, but only the Node bump actually unblocked anything — the library-build, lint, and misc-toolchain PRs were always independent of Storybook and Twig, and still are. They can land before or after the Storybook work in any order.

We moved Storybook 10 + Vite to the front because it deletes around ten dependencies rather than upgrading them, so it shrinks the backlog instead of working through it.

Three things the Storybook work changed for the other PRs:

• The library-build PR picks up one extra task: removing the temporary @types/node override. Webpack 4's tree was pinning that package at 12.20.6, and removing webpack let it float to a version TypeScript 4.9 can't parse.
• eslint-plugin-mdx 3 moved out of the Storybook PR and into the lint PR. It was blocked by MDX 1; now that the story files are MDX 3 it should be straightforward.
• Prettier 3 gained a second benefit — it unblocks restoring @whitespace/storybook-addon-html at v9.

Also recorded above: the suggested "split PR 5" approach is a dead end (Storybook's own mdx-to-csf codemod can't parse MDX 1 input, and Storybook 10 dropped the codemod entirely), plus a reference table of the Storybook 6 → 10 API moves so the next person doesn't have to rediscover them.

[spaceninja]

Handoff / current state

Recording where things stand so this can be picked up cold.

Shipped

• Upgrade CI and local development to Node 24 #2392 — Node 16 → 24. Merged. Added a temporary util shim for Twing 3, since removed.
• Revert @svgr/webpack to v5 for webpack 4 compatibility #2395 — revert @svgr/webpack to v5. Merged. v8 uses the webpack 5 loader API, so all 48 icons silently failed to compile on webpack 4 and the Icons page rendered blank. Superseded by Upgrade to Storybook 10 + Vite, and Twing 7 #2405, which drops the package entirely.

In review

#2405 — Storybook 10 + Vite + Twing 7. Three commits, all CI green. Awaiting review, then Gerardo.

Verified: lint:check, type, build, test (9 suites / 25 tests / 20 snapshots), build-storybook, and a headless sweep of all 253 stories and 84 docs pages — no empty or failed renders. Twig source previews show {% include %} snippets with syntax highlighting.

Three defects were found by eyeballing the deploy preview after the automated sweep passed, and are fixed in the last commit — worth noting because they show the limits of the sweep, which only checks that something rendered, not that it rendered correctly:

• Modular Scale table showed steps -60, -61 and sizes 0em. Token values are strings, so minimumStep + index concatenated. The for loop it replaced got away with it because i++ coerces.
• Fonts 404ed. Fixed by making the font path a configurable Sass variable — see the PR body.
• Sky Nav rendered open with no toggle after navigating between stories: useEffect(fn, []) runs once per preview session, and the template's no-js class is cleared by an inline <script> that never runs when markup is injected as a string.

Remaining work, in no required order

Only the Node bump ever unblocked anything; these are independent.

• Library build — rollup 2→4, rollup-plugin-dts 6, @rollup/plugin-terser 1, @rollup/plugin-babel 7, @rollup/plugin-node-resolve 16, TypeScript 5. Also removes the @types/node override added in Upgrade to Storybook 10 + Vite, and Twing 7 #2405 (overrides in package.json, pinned to 20.19.9). Webpack 4's tree held that package at 12.20.6; removing webpack let it float to 26.2.0, which TypeScript 4.9 cannot parse — and skipLibCheck does not suppress parse errors. TS 5 forces rollup-plugin-dts 6, which forces rollup 4, which is why these travel together.
• Lint & format — prettier 3, eslint, stylelint 17 + configs, and eslint-plugin-mdx 3. Two things unblock once Prettier is on 3:
  • *.mdx can come out of .prettierignore. Prettier 2 corrupts MDX 3 files: it rewrites the required {/* … */} comments into {/_ … _/} (reading the asterisks as markdown emphasis) and glues self-closing JSX onto the following markdown block.
  • @whitespace/storybook-addon-html v9 can be restored; it supports Storybook 10 but requires Prettier ^3.7.1.
• Misc toolchain — jest 30, style-dictionary 5, cssnano 8, js-yaml 5, npm-run-all2 9, sass.
• Remove Gulp — 286 lines across 5 tasks, 6 gulp-* dependencies. Thinner than it looks: gulpfile.js/tasks/build-tokens.js is a 5-line wrapper that shells out to npm run preprocess:tokens (delete outright), and build-scripts.js is already plain Rollup API.

Smaller follow-ups discovered along the way

• Type-check story files. src/**/*.stories.js is excluded in tsconfig.json. Converting MDX to JS brought 250+ story functions under checkJs for the first time — 269 errors. Excluding preserved the previous coverage (they were never checked as MDX) rather than widening Upgrade to Storybook 10 + Vite, and Twing 7 #2405. Worth doing properly.
• Revisit the docs.story.inline: false workarounds. Several stories disable inline rendering, and the comments blame html-to-react, which Upgrade to Storybook 10 + Vite, and Twing 7 #2405 removes — Storybook 10's HTML renderer inlines natively. They may be unnecessary now. Left alone deliberately, since changing them alters rendering behaviour.
• gulp-svgmin v4 warning. You are trying to enable removeXMLNS which is not part of preset — that optimisation is silently not applied to generated Twig SVGs. The SVGO plugin config needs updating.
• engines.node is still >=12.16.3. Deliberately untouched: it describes what consumers of the published package need, not our dev environment, so raising it is a consumer-facing change needing a changeset. Stale, but its own decision.

Notes for whoever picks this up

• Use Node 24.19.0 (nvm use, or .nvmrc). The machine's default Node is newer than CI's, and npm install under it will float @types/node and produce a different lockfile.
• The lockfile is lockfileVersion: 2. Regenerate with npm 8 (Node 16/24 era) rather than npm 11, or the whole file rewrites to v3.
• Don't trust --fix blindly here. Three autofixers actively introduced bugs during Upgrade to Storybook 10 + Vite, and Twing 7 #2405: Prettier 2 on MDX (above), and ESLint's n/file-extension-in-import appending extensions to package export subpaths (storybook/preview-api → .js) and after Vite query suffixes (x.twig?raw → ?raw.twig). That rule is now disabled for *.mdx, *.stories.js and .storybook/** for exactly this reason.
• A green build-storybook does not mean the stories work. It reported success while 47 stories rendered blank and while every icon silently failed to compile. The check that actually caught things was loading each story ID in headless Chrome and asserting #storybook-root had content and no error banner — worth rebuilding if more Storybook work is coming.
• Renovate/Dependabot churn is expected and should be left alone. Closing PRs just makes more from the backlog; a lot of it evaporates as these upgrades land.

[spaceninja]

Status update: library build shipped, Storybook PR rebased

Shipped

#2406 — Library build. Merged. rollup 2 → 4, rollup-plugin-dts 4 → 6, @rollup/plugin-terser 0.4 → 1, @rollup/plugin-babel 6 → 7, @rollup/plugin-node-resolve 13 → 16, TypeScript 4.9 → 5.9.

No build code changed — build-scripts.js was already on the plain Rollup JS API with the modern scoped plugins, so all six majors were drop-in. The diff was 12 lines of package.json plus the lockfile.

One thing worth recording, because it was not expected: the published UMD bundles shrank about 5×. sky-nav.ts imports the generated token module for three values, and rollup 2 emitted all 97KB of it; rollup 4 tree-shakes the object down to the reachable leaves. dist/cloudfour-patterns.js went 116KB → 21KB and .min.js 37KB → 7.8KB, with identical exports. dist/cloudfour-patterns.mjs is byte-for-byte unchanged, which explains the asymmetry: terser's module: true pass was already doing this elimination on the ESM output, so only the UMD builds — which terser cannot treat as a module — were carrying the dead tokens. That was latent bloat in main/unpkg specifically, not something the upgrade introduced.

In review

#2405 — Storybook 10 + Vite + Twing 7. Rebased onto main after #2406, all CI green, still awaiting review.

Only the first of its four commits conflicted, and only in package.json / package-lock.json — resolved as this branch's Storybook/Vite packages plus main's upgraded rollup toolchain. For the lockfile, main's version was taken as the base and npm 8 re-applied the branch's package.json on top, so the diff reads against the new main rather than as a merge artifact.

Two corrections to the plan above

The @types/node override removal did not happen in #2406. The plan listed it there, but that overrides block only ever existed on #2405's branch — main had no override at all, because webpack 4's tree was still pinning @types/node to 12.20.6. So it became a rebase-time step for whichever PR merged second, and it landed with the #2405 rebase instead. It works: with the override gone, @types/node floats to 26.2.0 and npm run type passes under TypeScript 5.9. The distinction the notes drew held up exactly — skipLibCheck covers the residual Buffer/Uint8Array check errors, and TypeScript 5 no longer produces the parse errors that skipLibCheck could not suppress.

"TypeScript 5" should be read as a ceiling, not a starting point. TypeScript's current release is 7.0.2, and rollup-plugin-dts 6 happily accepts ^4.5 || ^5 || ^6 || ^7 — so it is not the constraint anyone would guess. The real limit is @typescript-eslint, held at 5.17 by @cloudfour/eslint-plugin, which peers on ESLint 8. TypeScript 6 also removes moduleResolution: "node", which tsconfig.json still uses, and 7 is the Go-based native compiler rewrite. Going past TypeScript 5 is gated on the lint PR, and is worth treating as its own piece of work rather than a version bump. TypeScript 5.9 does not warn about moduleResolution: "node", so tsconfig.json was left alone.

A note on changesets, since the sequence has now hit both cases

PRs 1 and 2 correctly had none — they changed only dev tooling. The test that actually decides it is whether the PR changes a file we publish, per the files array in package.json:

• Upgrade the library build to Rollup 4 and TypeScript 5 #2406 got a patch changeset for the UMD size reduction, since it changes dist.
• Upgrade to Storybook 10 + Vite, and Twing 7 #2405 got three (net minor), because three of its fixes are in published files rather than tooling: base/fonts gaining a configurable $dir (a new public Sass API — minor), footnote-link.twig moving off the spaceless tag Twig 3 removed (patch), and initSkyNav clearing no-js (patch). dist/standalone.css is byte-for-byte identical, which is what makes the $dir change additive rather than a breaking path change.

Two published files needed no entry: src/index.scss is excluded from files, and src/index-with-dependencies.scss imports from node_modules and documents itself as Storybook-only, so no consumer can use it.

Related: #2405's body never actually documented the font fix, despite the handoff comment above pointing readers to it. It does now.

Remaining work, still in no required order

• Lint & format — prettier 3, eslint, stylelint 17 + configs, eslint-plugin-mdx 3. Unchanged, except that it now also gates any move past TypeScript 5 (above). Still unblocks taking *.mdx out of .prettierignore and restoring @whitespace/storybook-addon-html at v9.
• Misc toolchain — jest 30, style-dictionary 5, cssnano 8, js-yaml 5, npm-run-all2 9, sass.
• Remove Gulp — 286 lines across 5 tasks, 6 gulp-* dependencies.

Smaller follow-ups

Carrying forward, unchanged: type-checking src/**/*.stories.js; revisiting the docs.story.inline: false workarounds; the gulp-svgmin removeXMLNS warning; and the stale engines.node: ">=12.16.3".

One new one:

• Storybook demo args leak into the published types. dist/cloudfour-patterns.d.ts exports defaultArgs and defaultArgTypes, which come from src/components/*/*-args.js being caught by the rollup entry glob in build-scripts.js. Same class of bug Upgrade to Storybook 10 + Vite, and Twing 7 #2405 fixed for .stories.js, just for the args files. Pre-existing and unrelated to either upgrade, but now visible in the type output.

One more environment note

Worth adding to the notes above: when rebasing between these branches, rollup deduped to a single copy. #2405 previously carried rollup 2.80 as a devDependency alongside the 4.x copy Vite 8 pulls in, and npm silently nested both. Aligning the devDependency with what Vite already requires collapsed it to one 4.62.5. It only shows up in the lockfile, not the build output, so it is easy to miss.

[spaceninja]

Status update: Storybook 10 + Vite shipped — half the sequence is done

#2405 is merged (96fd86e1). With #2392, #2395 and #2406, items 1–3 of the sequence are complete and checked off above. The webpack toolchain is gone from package.json entirely — the only match for webpack|loader|svgr on main is now vite-plugin-svgr, which is the Vite replacement.

Two entries in the plan above were corrected rather than checked off, since both spike predictions turned out to be wrong in ways worth recording:

• The Sass glob importer was deleted, not rewritten. The spike estimated ~40 lines to port it to Sass's modern canonicalize/load API. A modern importer owns a URL namespace, so everything reached through it comes back to it to resolve with no fallback to Sass's own loader — expanding one glob made us responsible for reimplementing Sass's _partial and index lookup rules by hand. All 57 stylesheets are committed source files, so src/index.scss lists them explicitly and no Sass configuration is needed anywhere.
• The @types/node override never landed. Sequencing Upgrade the library build to Rollup 4 and TypeScript 5 #2406 first meant Upgrade to Storybook 10 + Vite, and Twing 7 #2405 could rebase onto TypeScript 5.9 and drop the pin. There is no overrides block on main.

What's left

Verified against main rather than from the plan, with current npm latest for comparison:

Item	Package	On main	Latest
4. Lint & format	prettier	2.8.8	3.9.6
	eslint	8.33.0	10.8.1
	stylelint	14.16.1	17.14.1
	eslint-plugin-mdx	1.17.1	3.8.1
	stylelint-config-cloudfour	6.1.0	10.0.0
5. Misc toolchain	jest	28.1.3	30.4.2
	style-dictionary	3.9.2	5.5.2
	cssnano	5.1.15	8.0.7
	js-yaml	4.3.1	5.3.0
	npm-run-all2	8.0.4	9.0.3
6. Remove Gulp	gulp + 5 gulp-*	—	282 lines across 5 tasks

Item 4 is the one with knock-on value: Prettier 3 unblocks restoring @whitespace/storybook-addon-html at v9, and it lets us drop the *.mdx line from .prettierignore that #2405 had to add — Prettier 2 corrupts MDX 3 files by rewriting {/* ... */} comments into {/_ ... _/}.

Release pending

main is at 17.1.0 with four unreleased changesets — three patch (Sky Nav string injection, Footnote Link spaceless, UMD bundle shrink) and one minor (base/fonts $dir), so the next release is 17.2.0.

Still open, unchanged

• engines.node is still ">=12.16.3". It describes what consumers need rather than our dev environment, so it was deliberately left alone — but it's stale and wants its own decision.
• gulp-svgmin v4 still warns You are trying to enable removeXMLNS which is not part of preset.
• We still run both Renovate and Dependabot, and Renovate's :automergeMinor still can't fire because branch protection requires an approving review.