[RFC] OXC fast path for CSF indexing

[EastonShin]

Summary

Storybook already ships and uses OXC for server-side module graph work (#34625). This RFC explores reusing that existing parser infrastructure for CSF indexing, without introducing a new dependency. Statically analyzable story files are indexed with oxc-parser; everything else falls back to the existing Babel/CsfFile path. In a proof of concept, 96.3% of this repository's 706 story files take the fast path with zero output mismatches, and storybook index on Storybook's internal UI drops from ~7.97s to ~5.95s.

Problem Statement

• Every storybook dev, storybook build and storybook index run parses every story file with Babel to build the story index.
• Indexing only needs a small, read-only slice of each file (meta title/id/tags/component, story export names, a few annotations), but pays for a full Babel parse and traversal.
• Most story files use a handful of static shapes that don't need that machinery, so index generation scales with project size more than it has to.

Non-goals

• Replacing Babel/CsfFile. It is still used for everything that transforms or writes CSF (vitest transform, save-story, docs enrichment), and for every shape the fast path doesn't support.
• Changing index output. The fast path must produce exactly what Babel produces, or step aside.
• Supporting every CSF shape. Uncommon or dynamic shapes are expected to keep using the fallback.
• Changing the startup architecture (builders, worker scheduling, caching).

Implementation

• A new internal indexCsfWithOxc(code, fileName, options) returns IndexInput[] or null ("unsupported shape").
• The built-in csfIndexer tries the fast path first and falls back to loadCsf(...).parse().indexInputs on null. The experimental flag is off by default.
• The existing Babel/CsfFile implementation remains the reference path during the experimental phase. Unsupported or uncertain shapes fall back to it.
• Shapes currently handled: CSF 1–3 object and function stories, CSF2 Template.bind({}), legacy story annotations (Story.storyName = ..., Story.play = ...), static includeStories / excludeStories, and CSF4 preview.meta() / meta.story() / meta.extend() when preview is imported from .storybook/preview.
• Shapes that fall back: non-object default exports, export { x as y } specifiers, export *, __namedExportsOrder, factory meta defined outside the file, story-level .extend(), and parse errors (e.g. Flow).

Correctness

• 706 story files in this repository compared against Babel output: 0 output mismatches
• 96.3% (680) handled by the OXC fast path
• On Storybook's internal UI (1768 index entries), index.json is byte-identical with and without the fast path

Performance (macOS, Node 22)

• Repository-wide isolated CSF indexing benchmark: ~4.5× faster
• End-to-end storybook index on Storybook's internal UI: ~7.97s → ~5.95s (~25% reduction), averaged over 6 alternating runs

Compatibility

• The 26 files that don't take the fast path fall back deterministically (same files, same reasons, across runs and refactors).

Proof of concept: https://github.com/EastonShin/storybook/tree/feat/native-csf-indexer-poc

Prior Art

• Storybook's change detection already builds its module graph with OXC (Change Detection: Build module graph with oxc tooling #34625), including a shared storybook/internal/oxc-parser wrapper and parse worker pool. This proposal reuses that existing direction for CSF indexing rather than introducing a new parser dependency.

Deliverables

1. Move the fast path onto storybook/internal/oxc-parser with typed OXC AST nodes, behind an experimental feature flag (e.g. features.experimentalOxcIndexer).
2. Add a parity check that runs both indexers over the repository's story files and fails on any output mismatch, and wire it into CI.
3. Collect feedback from projects that opt in (fast-path coverage, mismatches), then decide whether to enable the fast path by default.

Risks

• Drift between the two paths. A change to CsfFile semantics that the fast path doesn't mirror could produce different index output. Mitigation: the fast path only handles shapes it can prove, and the CI parity gate catches drift on the repository's story files.
• In-flight CsfFile changes. feat(csf-tools): implement factory meta resolution and enhance story import handling #36272 (cross-file factory meta resolution) is compatible by design: when OXC can't resolve factory meta locally, it returns null and Babel handles the file. The correctness risk is low. The cost is lower fast-path coverage for those files. Core: Recognise .extend() calls as CSF factory stories in enrichCsfStory #35339 (.extend() as factory stories) and Core: Parse modern Flow syntax in CSF files with hermes-parser #35848 (Flow via hermes-parser) likewise only affect files that already fall back.
• Maintenance cost of a second, read-only code path (~460 lines in the PoC).

Unresolved Questions

• What compatibility strategy would be acceptable for an OXC fast path during the experimental phase? One option is to keep Babel/CsfFile as the fallback/reference path and add a CI parity gate over the repository's story corpus.
• How should the fast path track in-flight CsfFile changes such as feat(csf-tools): implement factory meta resolution and enhance story import handling #36272?
• Is features.experimentalOxcIndexer the right flag shape?
• Should indexing reuse the storybook/internal/oxc-parser worker pool, or stay synchronous like the current indexer?

Alternatives considered / Abandoned Ideas

• Replacing Babel in CsfFile entirely. CsfFile also backs transforms and CSF writing, so swapping its AST would be a far larger and riskier change. A read-only fast path with fallback keeps the blast radius small.
• Parallelizing Babel indexing across workers. This is orthogonal: it spreads the same CPU cost across workers without reducing it, and it could be combined with this proposal later.

---

Disclosure: I used Claude (Claude Code) to help build the proof of concept, run the benchmarks and draft this RFC. I reviewed the results and the text myself.

[Sidnioulz]

Great idea, @EastonShin! I believe replacing Babel is the long-term goal though I'm not sure what all the technical constraints are for this to happen.

I believe we'll have very little appetite for owning two indexers instead of one, though. As you pointed out, we'd need to ensure API equivalence. As CSF 4 becomes default in Storybook 11, it's quite possible we'll get PRs on the code that extracts static properties for the index, so the risk is real.

This means we'd need to add CI test paths for both implementations. That's also a good reason to prefer replacements over duplications of internal APIs.

My personal opinion is that "Replacing Babel in CsfFile entirely" would be a great goal for this RFC. It's definitely a bigger piece of work but it's also a bigger net benefit and it avoids having to still preserve Babel!

@JReinhold, @huang-julien, @shilman FYI :)

[shilman]

Love this. The team should evaluate this technically but from a product standpoint it makes complete sense and I'm in favor of pursuing it.

Can somebody sketch out the entire path to phasing out Babel assuming that this is the best path forward? This RFC gets us to be able to make the comparison, but I'm assuming OXC will win hands down. At that point can we just remove Babel entirely? If not, what's blocking us? I don't want to get into a situation where we're supporting both long term.

[EastonShin]

@shilman @Sidnioulz @JReinhold @huang-julien

Absolutely. I’d be happy to take this on and map out the full path from the current OXC fast path to removing Babel entirely, including what the remaining blockers are and how we can eliminate them. I’ll dig into it and put together a concrete migration plan.

[Sidnioulz]

@EastonShin feel free to get started and build a proof of concept! That'd be lovely.

I just wanna make sure you know that we might have requirements that aren't visible upfront. Michael asked the team to think about potential caveats so we can update this thread async if we think of any potential complication.

If you manage to pull off the PoC, we can then use that to understand the exact performance benefits, potential trade-offs, and whether we need to go through an experimental phase or feature flag to push it to users.

[EastonShin]

@Sidnioulz Thanks, sounds good! Understood that there may be requirements we can't see yet. I'll keep the PoC easy to adjust as caveats come in.

Here's how I'm planning to scope it, so the team can flag anything early.

What the PoC will replace

The goal is a branch where csf-tools runs on OXC end to end, with no Babel and no fallback path:

Read path: CsfFile.parse() / indexing and read-only ConfigFile (readConfig / loadConfig) on storybook/internal/oxc-parser.

Write path: CsfObject mutations / save-story and ConfigFile writes, using OXC spans + magic-string instead of recast. This is the riskiest part, so it goes first.

Transforms: enrichCsf (docs csf-plugin) and vitestTransform / componentTransform, including source maps.

One consumer outside csf-tools: React's enrichCsf / component manifest, to validate the API that replaces direct access to CsfFile._ast / _storyExports.

The other renderers' docgen (Vue, web components, Angular), the CLI codemods, and mocking-utils stay on Babel in the PoC. Once the approach is validated, they're mechanical follow-ups.

How I'll measure it

Correctness: the existing CsfFile, ConfigFile (including ConfigFile.write), CsfObject, enrichCsf and vitest transformer test suites pass unchanged. Wherever a snapshot changes, I'll list the diff explicitly. On top of that, index.json stays byte-identical on the internal UI.

Performance: storybook index, storybook build with docs (which exercises enrichCsf), and the Vitest transform time, each compared against next.

Size: storybook package dist / install size with and without Babel bundled.

Known caveats so far

Formatting of inserted code. magic-string leaves untouched code byte-identical. Code that save-story or automigrations insert may be formatted slightly differently from what recast prints today.

Flow. OXC can't parse it, so Flow story files need hermes-parser (#35848) or a decision to stop supporting them.

AST exposure. CsfFile AST fields and storybook/internal/babel are used by renderers and possibly by community addons, so the final removal probably belongs in a major.

Out of scope: Babel used as the user's compiler (babel-loader in nextjs/ember, the babel / babelDefault presets) is a separate decision.

I'll report back here with the PoC branch and the numbers. Please add caveats to this thread as you think of them.

[EastonShin]

@Sidnioulz @shilman @JReinhold @huang-julien

The PoC is ready, and it now goes all the way: Babel and recast are removed from Storybook core. csf-tools runs on OXC end to end, every former Babel consumer has been ported, and there is no fallback path and no frozen Babel copy.

Draft PR (not for merge, for review and CI): #36613

Results

End to end (internal Storybook UI, next vs. this PR)

	next	PR
storybook index	1.65 s	0.84 s	2.0×
dev --smoke-test (median)	4.76 s	3.87 s	~1.2× (noisy)
full storybook build	~38.9 s	~36.0 s	~1.1×
storybook npm unpacked	17.75 MiB	15.50 MiB	−13%

Part of the gain is that the process no longer loads Babel at all. That costs ~64 ms per process or worker, versus ~5 ms for oxc-parser.

Per operation (all 587 story files in the repo, Babel vs. OXC, measured before the Babel implementation was deleted)

	Babel	OXC	Speedup
Indexing	579 ms	113 ms	5.1×
Docs enrichCsf	1,212 ms	255 ms	4.8×
vitestTransform	683 ms	216 ms	3.2×

Correctness

• 0 output differences from Babel for all three operations above.
• The internal UI's index.json (1,766 entries) is byte-identical.
• OXC exposes no scope information, so the PR ships a small scope analyzer. It matched Babel's bindings exactly: 99,828 bindings across 3,717 repo files, 0 mismatches. Unit tests pin the Babel-specific rules.
• Locally, all 48 projects compile and type-check. The full unit suite passes (14,293 tests), apart from 3 failures that are environment-only and also fail on next.

Writes preserve user code. Edits are span-based (magic-string) instead of reprinting the file with recast, so code we don't touch stays byte-for-byte identical. This applies to save-story, automigrations, addon-vitest setup and codemods alike.

What's left

• Some APIs change. CsfFile / CsfObject / CsfEnricher expose ESTree nodes instead of Babel ones, and storybook/internal/babel is gone. I've added a MIGRATION.md entry. This belongs in a major.
• CI. The PR needs a ci:normal label from a maintainer to run the sandboxes.
• Remaining Babel use. Babel stays only where it compiles user code (@storybook/nextjs, ember).

The PR is split into commits by area so it can be reviewed in order. If the direction looks good, it would land as three stacked PRs:

1. The OXC foundation. This only adds code, so it builds on its own.
2. The switch, reviewable commit by commit.
3. Babel and recast removal.