[kasperpeulen]

Summary

Devtools keeps working on Storybook 10 and also runs on Storybook 11, where storybookjs/storybook#36613 removes storybook/internal/babel and turns the csf-tools AST into ESTree (MIGRATION section). Only the code that reads or edits syntax nodes comes in two versions, one per Storybook. The rest is written once. The peer range stays >=10.6.0 || ^11.0.0-0, so the README's 10.6 floor holds.

This can be merged now. On Storybook 10, saved stories come out as they do on main. The storybook dev dependency stays 10.6.3, so CI runs the Babel path. The ESTree path uses the csf-tools API that #36947 made public, and its tests run by hand on a canary of Storybook next (see Validation). The Babel files can be deleted when devtools drops Storybook 10.

Why

Devtools used Babel in two places. The React transform parsed, traversed and reprinted every component module with Storybook's Babel. The story writer edited csf._ast and printed it with recast. On a Storybook with #36613, main's transform fails on every component module, and its writer always falls back to the regex splice.

Reading the diff

Each of the two picks its implementation the first time it runs, by whether storybook/internal/csf-tools has parseModule. There is no version check. Below, "Babel path" means Storybook 10 and the 11 prereleases without #36613, which still ship Babel. "ESTree path" means a Storybook with #36613. The ESTree path also needs #36947; no prerelease has #36613 without it.

src/frameworks/react/transform.ts holds everything after the parse, now shared: the RSC gate, the diagnostics, and the output. It asks a ModuleReader for a few facts about the module: the "use client" directive, whether it has JSX, the exported component bindings, and the patterns it can't tag. transform-babel.ts reads them with Storybook's Babel; that is the code from main, moved, now type-checked instead of @ts-nocheck. transform-estree.ts reads them with parseModule and walk. Both readers are imported statically, because the bundler transform hooks are synchronous. That is safe: neither touches storybook until it is called, and both go through the guarded peer loader.

The output is the same on both: the runtime import and the __chRegisterMeta calls are appended after the module body, so the module's own text and line numbers are kept. On main the module was reprinted by Babel's generator, and the transform returns no source map.

src/utils/csf-writer.ts keeps the writer's rules, written once. loadCsf().parse() validates the file. The writer dedupes the export name and renders the story. It then merges imports by exported symbol: it reuses an alias, promotes a type-only binding and picks a free name on a collision. The syntax steps go through a StoryFileEditor:

• csf-writer-babel.ts is the Babel AST and recast code from main, split into those steps.
• csf-writer-estree.ts edits the file through the CsfFile's own editor and adds value imports with CsfFile.setImport. Top-level names come from the editor's scope analysis, plus tsDeclarationNames. Every commit indexes the file again, and the writer checks that the appended export became a story. Promoting a type-only import to a value import is one commit: the type import's removal waits for the value import, because a file that re-exports the type (export type { fn }) is not valid CSF in between.

Each editor also tells a factory file from a CSF3 one. csf-tools have no public name for the meta variable, so the ESTree editor reads it off the .meta() call around the meta's object, or from the first meta.story() story.

The writer imports the editor for the installed Storybook with a dynamic import(), so neither loads on the other Storybook. The build keeps them as two lazy chunks. A failed load is not cached, so the next write tries again.

scripts/typecheck.mjs is what pnpm typecheck runs now. Only one path has its types installed, so it type-checks the project and leaves out diagnostics from the other path's files (src/**/*-babel.ts or src/**/*-estree.ts), picked the same way. src/test-utils/csf-tools.ts gives tests the installed path, a parse check with its parser, and a describe that skips itself on the other Storybook, with the reason in its name.

src/storybook-peer.ts keeps the prerelease part of the peer floor, so a floor can name an exact 11 prerelease.

What changes for users

On the Babel path, so on Storybook 10, one thing: the React transform no longer reprints a component module. It appends the runtime import and the tags, so stack traces and breakpoints line up with the source. The runtime import now loads after the module's own imports. The runtime imports nothing from the app, so the order does not matter. Saved stories are byte for byte what main writes.

On the ESTree path only, which is Storybook 11 with #36613, the writer's output differs from the Babel path's:

• An import added to an existing file goes directly below the other imports, without the blank line recast puts before it.
• An added import takes the quote most string literals in the file use, and the file's semicolon style. On the Babel path it follows the import sources.
• A new value import goes after the module's other value imports, which setImport decides.

On both paths, the regex splice now refuses, and writes nothing, when the story needs a value import of a name the file imports as a type only. It used to add a second import of that name.

Scope

• Supported framework impact considered (see docs/SUPPORTED_FRAMEWORKS.md)
• Shared e2e helpers/suite reused where possible
• First-click dock activation checked through the real UI for lifecycle changes

The transform change reaches the React, React 18, Rsbuild and Next playgrounds. The writer is shared by React and Vue. No E2E code and no dock lifecycle code changed.

Validation

With the storybook dev dependency as committed (10.6.3), so the Babel path:

pnpm build                # passes
pnpm test --run           # 499 passed
pnpm typecheck            # passes
pnpm exec playwright test # 193 passed
pnpm exec playwright test \
  --config=playwright.storybook.config.ts
# 5 passed, vue failed

Port 6006 was taken on my machine, so the Storybook suite ran with STORYBOOK_E2E_URL=http://localhost:6116. Its Vue run fails the same way on this PR's earlier head with 11.0.0-alpha.1: the preview throws "Cannot read properties of undefined (reading 'ReactCurrentDispatcher')", so it is not from this change.

ESTree path, on the canary https://pkg.pr.new/storybook@b26f35e (Storybook next at b26f35e1aff, 11.0.0-alpha.7 plus #36613 and #36947), installed locally and not committed: pnpm build and pnpm typecheck pass, and pnpm test --run passes 498 tests and skips the one Babel-only line-ending test from main. On that canary, one commit before the promotion fix, the Playwright suites gave the same results as above.

To run the ESTree tests:

pnpm add -D \
  storybook@https://pkg.pr.new/storybook@b26f35e
pnpm build
pnpm test --run
pnpm typecheck
git checkout package.json pnpm-lock.yaml
pnpm install --frozen-lockfile

Five React and Vue story-generator tests append to a file that needs a new import, so their output differs between the paths by that one blank line. They remove it with withoutAddedImportGap, check that it was there exactly on the Babel path, and match the snapshots of this PR's first commits. Both paths share one snapshot per test, which matters because vitest in CI mode fails on obsolete snapshots.

Build sizes, uncompressed:

• writer chunk: 27.9 kB on main, 27.7 kB at this PR's first commits, now 23.8 kB plus a 7.1 kB Babel chunk or a 10.0 kB ESTree chunk
• React framework chunk, with both readers: 13.5 kB on main, 12.9 kB at the first commits, now 18.5 kB

Screenshots / Evidence

No visible change.

Documentation

• Updated AGENTS.md if workflow/expectations changed
• Added/updated inline comments for non-obvious logic

docs/ARCHITECTURE.md and docs/REACT_PATTERNS.md describe both paths. AGENTS.md says how to check the other path.

PR Type

• Tests-only
• Implementation
• Docs
• Refactor

Notes for Reviewers

The shared writer and the ESTree editor use only public csf-tools API. The Babel editor reads _ast, _storyExports, _metaIsFactory and _metaVariableName with printCsf, as main does. Tests from main still read _metaIsFactory and _storyExports, since they run on both paths.

The ESTree path is picked on parseModule alone; no released Storybook has #36613 without #36947. CI runs the Babel path only, since that is the installed Storybook; run the ESTree tests by hand as above.

The Babel editor imports storybook/internal/babel through a variable. The playgrounds' Vite configs load the plugin from source, and Vite's config bundler resolved the literal import() up front, which failed on the canary and stopped every Playwright web server.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/storybookjs/storybook-devtools/@storybook/experimental-devtools@34

commit: 79d1e57