{"id":12749,"library":"react-docgen-typescript","title":"React TypeScript Docgen Parser","description":"This library, `react-docgen-typescript`, provides a robust parser for extracting documentation information from React components written in TypeScript. It analyzes TypeScript files to generate documentation data, similar to how `react-docgen` works for JavaScript components with `propTypes`. The current stable version is 2.4.0, with releases occurring semi-frequently, indicating active maintenance and feature development based on recent changelogs. Its primary differentiator is its native support for TypeScript, allowing it to correctly interpret complex type definitions, interfaces, and generics to generate detailed prop tables, including descriptions, types, and default values. It is often used in conjunction with tools like React Styleguidist to automatically generate component documentation.","status":"active","version":"2.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/styleguidist/react-docgen-typescript","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-docgen-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add react-docgen-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-docgen-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for parsing TypeScript files.","package":"typescript","optional":false}],"imports":[{"note":"'parse' is the core function for processing a single file. For CommonJS, the common pattern shown in the README is to import the entire module and then access 'parse' from the imported object.","wrong":"const docgen = require('react-docgen-typescript'); docgen.parse('./path/to/component')","symbol":"parse","correct":"import { parse } from 'react-docgen-typescript'"},{"note":"Used to create a parser instance with default TypeScript compiler options and custom docgen options.","wrong":"const docgen = require('react-docgen-typescript'); docgen.withDefaultConfig(options)","symbol":"withDefaultConfig","correct":"import { withDefaultConfig } from 'react-docgen-typescript'"},{"note":"Allows creating a parser using an existing tsconfig.json file for TypeScript configuration, which is recommended for most projects.","wrong":"const docgen = require('react-docgen-typescript'); docgen.withCustomConfig('./tsconfig.json', options)","symbol":"withCustomConfig","correct":"import { withCustomConfig } from 'react-docgen-typescript'"},{"note":"This is a TypeScript type definition for the structured output of the parser for a single component. It should be imported as a type.","symbol":"ComponentDoc","correct":"import type { ComponentDoc } from 'react-docgen-typescript'"}],"quickstart":{"code":"import { withCustomConfig } from 'react-docgen-typescript';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\n// Define a dummy component file for demonstration\nconst componentCode = `\nimport React from 'react';\n\ninterface ButtonProps {\n  /**\n   * The text content of the button.\n   */\n  label: string;\n  /**\n   * Is this the principal call to action on the page?\n   * @default false\n   */\n  primary?: boolean;\n  /**\n   * What background color to use\n   */\n  backgroundColor?: string;\n  /**\n   * How large should the button be?\n   * @default 'medium'\n   */\n  size?: 'small' | 'medium' | 'large';\n  /**\n   * Optional click handler\n   */\n  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;\n}\n\n/**\n * A primary button component\n */\nexport const Button: React.FC<ButtonProps> = ({\n  label,\n  primary = false,\n  backgroundColor,\n  size = 'medium',\n  onClick,\n}) => {\n  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';\n  return (\n    <button\n      type=\"button\"\n      className={['storybook-button', `storybook-button--${size}`, mode].join(' ')}\n      style={{ backgroundColor }}\n      onClick={onClick}\n    >\n      {label}\n    </button>\n  );\n};\n`;\n\nconst tempDir = path.join(__dirname, 'temp');\nif (!fs.existsSync(tempDir)) {\n  fs.mkdirSync(tempDir);\n}\nconst tempComponentPath = path.join(tempDir, 'Button.tsx');\nfs.writeFileSync(tempComponentPath, componentCode);\n\n// Create a basic tsconfig.json for the parser\nconst tsconfigPath = path.join(tempDir, 'tsconfig.json');\nfs.writeFileSync(tsconfigPath, JSON.stringify({\n  compilerOptions: {\n    jsx: \"react\",\n    module: \"ESNext\",\n    target: \"ESNext\",\n    esModuleInterop: true,\n    strict: true,\n    skipLibCheck: true,\n  },\n  include: [tempDir + \"/**/*\"]\n}, null, 2));\n\n\nconst parser = withCustomConfig(tsconfigPath, {\n  shouldExtractLiteralValuesFromEnum: true,\n  propFilter: {\n    skipPropsWithoutDoc: true,\n  },\n});\n\ntry {\n  const componentDocs = parser.parse(tempComponentPath);\n  console.log(JSON.stringify(componentDocs, null, 2));\n} catch (error) {\n  console.error(\"Error parsing component:\", error);\n} finally {\n  // Clean up temporary files\n  fs.unlinkSync(tempComponentPath);\n  fs.unlinkSync(tsconfigPath);\n  fs.rmdirSync(tempDir);\n}\n","lang":"typescript","description":"This example demonstrates how to parse a TypeScript React component using `withCustomConfig` to specify a `tsconfig.json` and custom docgen options, then prints the generated documentation to the console."},"warnings":[{"fix":"Upgrade your project's 'typescript' dependency to version 4.3.x or higher to meet the minimum requirement.","message":"Version 2.0.0 introduced a breaking change by requiring TypeScript 4.3 or newer due to the use of a new TypeScript API function. Projects using older TypeScript versions will encounter errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If conflicts or unexpected behavior arise, explicitly configure 'esModuleInterop' via `withCompilerOptions` or `withCustomConfig` to match your project's `tsconfig.json` settings.","message":"Starting from version 2.4.0, the 'esModuleInterop' compiler option is set as a default configuration during parsing when using `parse` or `withDefaultConfig`. If your project relies on specific 'esModuleInterop' behavior that conflicts with this default (e.g., explicit `false`), you might experience changes in how imports are resolved during parsing.","severity":"breaking","affected_versions":">=2.4.0"},{"fix":"Always ensure your project's 'typescript' dependency meets the peer dependency constraint specified in `react-docgen-typescript`'s `package.json`. Use `npm install typescript@latest` or a specific compatible version to resolve potential conflicts.","message":"The library depends on 'typescript' as a peer dependency. Incompatible 'typescript' versions (e.g., using an older version than '>= 4.3.x' with `react-docgen-typescript` v2.0.0+) can lead to parsing errors or unexpected behavior during documentation generation.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade 'react-docgen-typescript' to version 2.0.0 or newer to resolve this bug, which included fixes for tag text handling.","cause":"This error typically occurred in versions prior to 2.0.0 due to an issue with how JSDoc tag text was processed, where the 'text' property could be null or undefined.","error":"TypeError: (tag.text || \"\").trim is not a function"},{"fix":"Upgrade 'react-docgen-typescript' to version 2.0.0 or newer, as this was addressed in fixes for that major release.","cause":"This often indicates an issue in older versions (pre-2.0.0) where internal data structures for declarations or other parsed elements were unexpectedly undefined, leading to runtime errors when trying to access properties like 'length'.","error":"Cannot read property 'length' of undefined"},{"fix":"Ensure you are using 'react-docgen-typescript' version 1.20.5 or newer, or ideally any 2.x version, where these edge cases were resolved.","cause":"In older versions, particularly around 1.20.5, specific scenarios could lead to 'declarations' being undefined, causing runtime errors when attempting to access its 'length' property.","error":"Property 'declarations' of 'PropItem' is undefined or has no 'length' property"},{"fix":"Upgrade 'react-docgen-typescript' to version 2.2.2 or higher to fix the 'trimFileName' functionality in monorepos.","cause":"This was a specific bug in versions prior to 2.2.2 where the 'trimFileName' logic failed to correctly process file paths when used within a monorepo setup.","error":"trimFileName no longer works in a monorepo"}],"ecosystem":"npm"}