The changes in this PR were generated using Claude Code w/ Opus 4.8, I have verified the accuracy of its findings and benchmarks. I have reviewed the code myself and confirmed the accuracy of all claims here myself, and written this PR manually myself except where noted.

I'm opening this for consideration by the maintainers because I think this is a pretty big performance boost that is worth implementing. I don't have a strong preference for my PR being merged specifically, I'm 100% fine if this is just used as a proof-of-concept and a maintainer uses this concept for their own PR to actually implement this idea.

Note that #33909 did mention this optimization as a possibility, but it was never tested/implemented at the time.

It should also be noted that this may not be forward-compatible with the eventual TS 7.1 API which I presume will be used in the future. If we think that this changeset will potentially cause additional, undesired work for supporting TS 7.1 in the future, I'm also fine closing this PR on those grounds. But I doubt that should be a serious concern.

What I did

Basically, the ComponentMetaManager was creating one language service for each tsconfig.json file. That doesn't matter for a project with only one tsconfig, but will result in a lot of duplicated DocumentRegistry instances in a monorepo. TypeScript creates a private registry for each language service if you don't explicitly provide one, so the lib.d.ts, React's types, etc. were being duplicated for each language service. We can improve the runtime of the docgen server by sharing the DocumentRegistry across the separate language service instances.

This has no negative impact on single-tsconfig repos as the DocumentRegistry is created once, just like it was before on a single-tsconfig repo.

This won't have any performance improvement if different projects in a monorepo have entirely different tsconfig settings, but it still works fine and doesn't have any downside for a repo like that.

Measured on this repo's own Storybook (188 components across 7 projects, 20,657 SourceFiles of which only 4,763 are unique to the largest project).

Comparison of SourceFile objects before vs after:

Static build time, storybook build with experimentalDocgenServer on, three runs per branch:

next     15.24s  14.37s  15.44s
this PR  11.40s  11.01s  11.43s   (~25% faster)

The live JS heap is sampled in-process via a benchmark harness written with Claude (note that this doesn't matter as much for overall memory usage, see caveat below):

extraction time   7.17s   -> 5.12s   (-29%)
peak heap used    3507 MB -> 1929 MB (-45%)

The output is identical to the output of next.

Best as I've been able to tell in the benchmarking, there is no difference in the peak RSS of the storybook build process overall thanks to this PR, only the live heap used by the docgen server is reduced.

This should still help with the OOM issues (see #35260) in monorepos, because the heap-pressure recycler from #35305 is tripped less often with this change. Testing the same 188 components under a few different V8 heap limits:

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

There is one additional test added here to verify that the shared DocumentRegistry is actually being used. The existing test suite should also verify that nothing else broke with this change.

Manual testing

This bash script (written by Claude) can be used to verify that the build runtime is improved on this branch vs. the original

run_arm () {
  local ref=$1
  git checkout -q "$ref"
  yarn nx compile react --skip-nx-cache >/dev/null 2>&1

  if grep -rqi documentRegistry code/renderers/react/dist/; then
    echo "### $ref -> dist HAS the fix"
  else
    echo "### $ref -> dist does NOT have the fix"
  fi

  cd code
  for i in 1 2 3; do
    rm -rf "./sb-$ref-$i"
    STORYBOOK_EXPERIMENTAL_DOCGEN_SERVER=true STORYBOOK_DISABLE_TELEMETRY=1 \
      node core/dist/bin/dispatcher.js build --config-dir ./.storybook --output-dir "./sb-$ref-$i"
  done
  cd ..
}

run_arm next
run_arm <THIS-BRANCH>

After running the above, you can also diff the two docgen outputs to ensure that they are identical between this branch and next (note that you may need to ensure that this branch is rebased off latest next if any changes land before this gets tested):

diff -r code/sb-next-2/services/core/docgen code/sb-<THIS-BRANCH>-2/services/core/docgen

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Declare whether manual QA will be needed for this PR during the next release, through qa:needed or qa:skip

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>