Skip to content

React: Guard docgen extraction against TypeScript builds without the compiler API - #35834

Merged
ghengeveld merged 1 commit into
storybookjs:nextfrom
FrancoKaddour:fix/docgen-typescript7-missing-compiler-api
Oct 14, 2026
Merged

ghengeveld merged 1 commit into
storybookjs:nextfrom
FrancoKaddour:fix/docgen-typescript7-missing-compiler-api

Conversation

@FrancoKaddour

@FrancoKaddour FrancoKaddour commented Aug 10, 2026 •

Copy link
Copy Markdown
Contributor

#35792 reports that experimentalDocgenServer + componentsManifest on TypeScript 7 crashes the docgen worker with Cannot read properties of undefined (reading 'fileExists'). Root cause (well diagnosed by the reporter): TS 7's typescript package only exports lib/version.cjs from its main entry, so await import('typescript') resolves to a namespace with version but no compiler API (ts.sys is undefined).

On next the hard crash no longer reproduces the same way: the BaseComponentMetaManager refactor moved the first ts.sys access into construction (createDocumentRegistry(ts.sys.useCaseSensitiveFileNames)), so the existing try/catch around new ComponentMetaManager(ts) in both entry points already swallows it and falls back to undefined. But that fallback is silent in the docgen worker and mislabeled in the singleton ("TypeScript not available", when TS is installed) — so a TS 7 user just gets empty component docs with no explanation.

This PR makes that path explicit and diagnosable:

  • Fail fast at the invariant. ComponentMetaManager's constructor now asserts the resolved typescript actually exposes the compiler API and throws a clear, actionable error otherwise, instead of crashing later on a cryptic undefined read. Both call sites already catch and degrade gracefully.
  • Accurate diagnostics. The singleton no longer claims "TypeScript not available"; both entry points now logger.debug the real reason, so the TS 7 case is visible when debugging.
  • Removed a stray console.log({ tsconfigPath }) in getTsConfig that leaked to the dev-server stdout.

Testing

  • Added a regression test: constructing ComponentMetaManager with a version-only typescript stub (the TS 7 shape) throws the clear compiler-API error. Verified red/green — without the guard the constructor throws the cryptic Cannot read properties of undefined (reading 'useCaseSensitiveFileNames').
  • ComponentMetaManager.test.ts green (20/20).

Manual testing

  1. Run yarn task sandbox --template react-vite/default-ts --start-from auto
  2. In the sandbox, run yarn add -D typescript@7 and start Storybook with --loglevel debug
  3. Open the Docs page of the Button component: Storybook does not crash, and the log shows the [reactComponentMeta] message that the resolved typescript has no compiler API
  4. Run yarn add -D typescript@6 and restart: the Controls table shows the Button props again

Scope

This intentionally does not add TS 7 native-preview support for docgen (the compiler API genuinely isn't there) — it makes the unsupported path degrade cleanly and legibly instead of crashing. Happy to escalate the logger.debug to a one-time warn if you'd prefer TS 7 users to see it surfaced.

Related to #35792


🤖 AI disclosure: Implemented with AI assistance (Claude Code). The root-cause analysis, the red/green reproduction of the TypeScript 7 shape, and all verification were done and reviewed by me.

@FrancoKaddour FrancoKaddour changed the title fix(react): guard docgen extraction against typescript builds without the compiler API React: Guard docgen extraction against TypeScript builds without the compiler API Aug 21, 2026
… the compiler API

TypeScript 7's  package only exports version info from its main
entry, so  can resolve without the compiler API
( is undefined). Fail fast in the ComponentMetaManager constructor with
a clear, actionable error instead of crashing deep in project setup; make the
two degradation points log the real reason instead of a misleading "TypeScript
not available"; and drop a stray console.log in getTsConfig.

Closes storybookjs#35792
@ghengeveld
ghengeveld force-pushed the fix/docgen-typescript7-missing-compiler-api branch from 3de5f8c to 52685b7 Compare October 14, 2026 07:00
@ghengeveld

ghengeveld commented Oct 14, 2026 •

Copy link
Copy Markdown
Member

Hey @FrancoKaddour, thanks for this. I rebased the branch on next and resolved the conflicts. next now uses ts.default ?? ts in both entry points, so I kept that together with your logging. The stray console.log was already removed on next.

We plan to make docgen work with TypeScript 7 by falling back to @typescript/typescript6 when the project's typescript has no compiler API. Your guard stays useful as the last check when neither is available.

We'd like to move forward with the TS 7.1 compatibility work, and I'd like to give credit where it's due, so I'll finalize and merge your PR. The team can then wrap up the remainder of what's required for #35792 in a separate PR.

@ghengeveld ghengeveld added bug ci:normal Run CI workflows for most stable frameworks. Run this on PRs where ci:focus logic has blind spots. qa:skip Pull Requests that do not need any QA. (e.g. documentation) labels Oct 14, 2026
@ghengeveld ghengeveld self-assigned this Oct 14, 2026
@ghengeveld
ghengeveld marked this pull request as ready for review October 14, 2026 07:14
@coderabbitai

coderabbitai Bot commented Oct 14, 2026

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ef3ac710-e1d1-4ee4-91a7-4f8a2f6d1c37
📥 Commits

Reviewing files that changed from the base of the PR and between 8af3851 and 52685b7.

📒 Files selected for processing: 4
  • code/renderers/react/src/componentManifest/componentMeta/ComponentMetaManager.test.ts
  • code/renderers/react/src/componentManifest/componentMeta/ComponentMetaManager.ts
  • code/renderers/react/src/componentManifest/componentMetaManagerSingleton.ts
  • code/renderers/react/src/docgen/docgen-worker.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

Walkthrough

ComponentMetaManager now validates the TypeScript compiler API before setup. The component metadata singleton and React docgen worker log caught TypeScript initialization errors at debug level and continue to return undefined on their failure paths.

Changes

TypeScript initialization

Layer / File(s) Summary
Validate the compiler API
code/renderers/react/src/componentManifest/componentMeta/ComponentMetaManager.ts, code/renderers/react/src/componentManifest/componentMeta/ComponentMetaManager.test.ts
ComponentMetaManager checks that typescript.sys.fileExists is a function before creating its project factory. A test checks that a version-only TypeScript object produces an error mentioning “compiler API.”
Log initialization failures
code/renderers/react/src/componentManifest/componentMetaManagerSingleton.ts, code/renderers/react/src/docgen/docgen-worker.ts
The singleton and docgen worker log caught TypeScript initialization errors at debug level. Both failure paths still return undefined.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 52685

Missing TypeScript compiler APIs now produce a logged, handled fallback, and the logger is available in supported installations. No actionable merge risk is established.

✨ Finishing Touches: 💡 1
🛠️ Fix failing CI checks: 💡
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@ghengeveld
ghengeveld enabled auto-merge October 14, 2026 07:21
@ghengeveld ghengeveld added qa:skip Pull Requests that do not need any QA. (e.g. documentation) and removed qa:skip Pull Requests that do not need any QA. (e.g. documentation) labels Oct 14, 2026
@ghengeveld
ghengeveld disabled auto-merge October 14, 2026 08:05
@ghengeveld
ghengeveld merged commit 990f777 into storybookjs:next Oct 14, 2026
159 of 171 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 14, 2026
2 tasks done
ghengeveld added a commit to storybookjs/sandboxes that referenced this pull request Oct 14, 2026
Check the diff here: storybookjs/storybook@8af3851...50a8282

List of included PRs since previous version:
- storybookjs/storybook#36301 (sharadvc/cursor/fix-mcp-connect-agents-link-6fef)
- storybookjs/storybook#35863 (SnowingFox/fix/35862-server-channel-error-handler)
- storybookjs/storybook#36688 (ghengeveld/vitest-36221-leftovers)
- storybookjs/storybook#36746 (fix/bbc-local-story-manifest-snippets)
- storybookjs/storybook#36588 (fix/nextjs-router-mock-bfcache)
- storybookjs/storybook#36391 (agent/sto-492-eslint-cjs)
- storybookjs/storybook#36751 (agent/sto-280-prerelease-version-alignment)
- storybookjs/storybook#36768 (svelte-knip-cleanup)
- storybookjs/storybook#35834 (FrancoKaddour/fix/docgen-typescript7-missing-compiler-api)
- storybookjs/storybook#36770 (bryce-easygo/fix/svelte-csf-null-arg-snippet)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-scan:human bug ci:normal Run CI workflows for most stable frameworks. Run this on PRs where ci:focus logic has blind spots. qa:skip Pull Requests that do not need any QA. (e.g. documentation)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

⌂ 换网址