{"id":10541,"library":"babel-plugin-react-docgen-typescript","title":"Babel Plugin for React TypeScript Docgen","description":"babel-plugin-react-docgen-typescript is a Babel plugin designed to extract component documentation (docgen data) from React components written in TypeScript. It works by integrating into the Babel compilation pipeline, identifying and parsing TypeScript React files to generate metadata about their props, types, and descriptions. This data is typically consumed by documentation tools like Storybook to automatically generate prop tables and API documentation. The plugin, currently at version 1.5.1, explicitly leverages the `react-docgen-typescript` library for its core parsing logic. While functional, the plugin's documentation notes it's 'a bit of a hack' and can be 'very inefficient' if not properly configured with `include` and `exclude` regular expressions to limit the scope of files it processes. It does not specify a fixed release cadence but generally follows updates in the `react-docgen-typescript` or Babel ecosystems. Its main differentiator is its direct integration into Babel builds, offering a streamlined approach to collecting docgen data without requiring separate parsing steps.","status":"active","version":"1.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/strothj/babel-plugin-react-docgen-typescript","tags":["javascript"],"install":[{"cmd":"npm install babel-plugin-react-docgen-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-react-docgen-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-react-docgen-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for any Babel plugin.","package":"@babel/core","optional":false}],"imports":[{"note":"This package is a Babel plugin, configured via its string name in the `plugins` array of your `.babelrc` or `babel.config.js` file. It is not typically imported directly into application JavaScript/TypeScript files.","wrong":"import plugin from 'babel-plugin-react-docgen-typescript'","symbol":"babel-plugin-react-docgen-typescript","correct":"plugins: [[\"babel-plugin-react-docgen-typescript\", { /* options */ }]]"}],"quickstart":{"code":"// 1. Install necessary packages:\n// npm install --save-dev babel-plugin-react-docgen-typescript @babel/core typescript react @babel/preset-typescript @babel/preset-react\n\n// 2. Configure your .babelrc (or babel.config.js):\n// .babelrc\nconst babelConfig = {\n  plugins: [\n    [\n      \"babel-plugin-react-docgen-typescript\",\n      {\n        // Name of the global object where docgen data will be collected.\n        // Useful for integration with tools like Storybook.\n        \"docgenCollectionName\": \"STORYBOOK_REACT_CLASSES\",\n        // Regex to include files for parsing. Crucial for performance.\n        \"include\": \"src/components/.*\\\\.tsx$\",\n        // Regex to exclude files, e.g., stories or test files.\n        \"exclude\": \"src/components/.*\\\\.stories\\\\.tsx$\"\n      }\n    ]\n  ],\n  // Add these presets if you're working with TypeScript and React\n  \"presets\": [\"@babel/preset-typescript\", \"@babel/preset-react\"]\n};\n\n// 3. Example TypeScript React Component (e.g., src/components/Button.tsx):\n/*\nimport React from 'react';\n\ninterface ButtonProps {\n  /**\n   * The text content for the button.\n   */\n  label: string;\n  /**\n   * Callback when the button is clicked.\n   */\n  onClick: () => void;\n}\n\n/**\n * A simple button component with JSDoc comments for docgen.\n */\nexport const Button: React.FC<ButtonProps> = ({ label, onClick }) => {\n  return (\n    <button onClick={onClick}>\n      {label}\n    </button>\n  );\n};\n*/\n\n// During the Babel compilation process, this plugin will extract\n// documentation from 'Button.tsx' (if it matches 'include') and store it \n// in 'global.STORYBOOK_REACT_CLASSES'. This data can then be consumed by \n// documentation tools like Storybook to generate prop tables.","lang":"typescript","description":"This quickstart demonstrates how to install `babel-plugin-react-docgen-typescript` and configure it in your `.babelrc` to extract documentation from TypeScript React components, useful for tools like Storybook."},"warnings":[{"fix":"Always define `include` and `exclude` regular expressions in your plugin options to process only relevant component files and avoid unnecessary parsing.","message":"The plugin can introduce significant performance overhead during the build process if `include` and `exclude` options are not properly configured.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be mindful of this architectural note and test thoroughly when updating related dependencies (Babel, TypeScript, React) or when complex component patterns are used. Consider its fitness for critical production build pipelines.","message":"The plugin is described by its maintainers as 'a bit of a hack', which might imply a less robust or non-standard implementation, potentially leading to unexpected behavior or fragility with future Babel/TypeScript updates.","severity":"gotcha","affected_versions":"*"},{"fix":"Monitor release notes for both `babel-plugin-react-docgen-typescript` and `react-docgen-typescript` to anticipate potential issues when updating dependencies. Thoroughly test after any dependency updates.","message":"The plugin internally relies on `react-docgen-typescript` for its core parsing logic. Breaking changes or updates in `react-docgen-typescript` might indirectly affect this plugin's behavior or compatibility.","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":"Ensure `npm install --save-dev babel-plugin-react-docgen-typescript @babel/core` has been run and that the plugin is correctly listed in your Babel configuration.","cause":"The package `babel-plugin-react-docgen-typescript` or its peer dependency `@babel/core` is not installed or not resolvable by Babel.","error":"Plugin 'babel-plugin-react-docgen-typescript' not found."},{"fix":"Add specific `include` and `exclude` regular expressions in your `.babelrc` plugin options (e.g., `\"include\": \"src/components/.*\\\\.tsx$\", \"exclude\": \"src/components/.*\\\\.stories\\\\.tsx$\"`) to limit processing only to actual component files.","cause":"The plugin is processing too many files, potentially all `.tsx` files in your project, due to broad or missing `include`/`exclude` configurations.","error":"My build process is significantly slower after adding babel-plugin-react-docgen-typescript."},{"fix":"Verify that `docgenCollectionName` matches what your documentation tool expects. Double-check `include` and `exclude` regex patterns to confirm they are correctly targeting your component files. Ensure your Babel configuration is applied to the directories containing your React components.","cause":"This can be caused by an incorrect `docgenCollectionName`, inaccurate `include`/`exclude` patterns, or the Babel plugin not being applied to the correct component files during the build.","error":"Docgen data (prop tables, component descriptions) is not appearing in Storybook or other documentation tools."}],"ecosystem":"npm"}