[Documentation]: TypeScript `parseJsonConfigFileContent()` Doesn't Follow References

[endurance-chorus]

Describe the problem

Note

This is a TypeScript design decision, not a Storybook bug. However, Storybook's documentation could be improved to explain this limitation and provide guidance for monorepo setups.

The Issue

TypeScript's ts.parseJsonConfigFileContent() API only reads files from direct include/files arrays. It does NOT follow references to collect files from referenced projects.

This is by design in TypeScript—project references create separate compilation units, and parseJsonConfigFileContent() is meant to parse a single project's configuration.

How Storybook Uses This API

Storybook uses ts.parseJsonConfigFileContent() to create a TypeScript program for react-docgen-typescript:

// Simplified from Storybook source
const configPath = findTsconfigPath(process.cwd());
const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
const parsedConfig = ts.parseJsonConfigFileContent(
  configFile.config,
  ts.sys,
  path.dirname(configPath)
);

// parsedConfig.fileNames will be EMPTY for solution-style tsconfigs!
const program = ts.createProgram({
  rootNames: parsedConfig.fileNames,  // []
  options: parsedConfig.options,
});

The Problem in Solution-Style Monorepos

In solution-style monorepos, the root tsconfig.json typically looks like:

{
  "compilerOptions": {
    "composite": true,
    "declaration": true
  },
  "include": [],
  "files": [],
  "references": [
    { "path": "./packages/ui" },
    { "path": "./packages/app" },
    { "path": "./packages/utils" }
  ]
}

When Storybook parses this config:

1. include is empty → no files matched
2. files is empty → no explicit files
3. references are NOT followed
4. Result: parsedConfig.fileNames is []
5. TypeScript program has no source files
6. react-docgen-typescript cannot extract any component documentation

Why This Matters

This limitation compounds with this bug: #34386

Even if a user provides tsconfigPath pointing to a properly configured tsconfig, Bug #34386 prevents that path from being used.

Documentation Suggestion

Storybook's documentation should include a section on monorepo configuration that explains:

1. The limitation: TypeScript's parseJsonConfigFileContent() doesn't follow project references

2. The solution: Create a dedicated tsconfig for Storybook that explicitly includes all source files:

   // tsconfig.storybook.json
   {
     "extends": "./tsconfig.base.json",
     "compilerOptions": {
       "composite": false,  // Not needed for Storybook
       "noEmit": true
     },
     "include": [
       "packages/*/src/**/*.ts",
       "packages/*/src/**/*.tsx",
       ".storybook/**/*.ts"
     ]
   }

3. The configuration: How to use this tsconfig with reactDocgenTypescriptOptions.tsconfigPath (once Bug [Bug]: getParser5() Ignores tsconfigPath Option #34386 is fixed)

Related TypeScript Documentation

• TypeScript Project References
• ts.parseJsonConfigFileContent() API

Additional context

No response