{"id":11933,"library":"remark-mdx-react-docgen-typescript","title":"MDX React Docgen Typescript Remark Plugin","description":"remark-mdx-react-docgen-typescript is a Remark plugin designed to integrate `react-docgen-typescript` functionality directly into MDX documents. It allows developers to automatically extract and display TypeScript React component documentation within their MDX content using a directive syntax (e.g., `::component-docs{file=\"./Component.tsx\"}`). The plugin processes MDX files, identifies these directives, and replaces them with JSX `<ComponentDocs>` elements containing `propsData` derived from the specified React component files. The current stable version is 1.0.1. Its release cadence appears to be ad-hoc, with recent updates in late 2023. Key differentiators include its tight integration with the `unified` and `remark` ecosystems, specifically for MDX, and its ability to leverage `react-docgen-typescript` for type-aware documentation generation, making it suitable for monorepos or design systems that use TypeScript and MDX for documentation.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/Rippling/remark-mdx-react-docgen-typescript","tags":["javascript","markdown","react-docgen-typescript","mdast","plugin","remark","remark-plugin","unified","typescript"],"install":[{"cmd":"npm install remark-mdx-react-docgen-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add remark-mdx-react-docgen-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add remark-mdx-react-docgen-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for processing the custom `::component-docs` directive syntax in MDX.","package":"remark-directive","optional":false},{"reason":"Core dependency for extracting component documentation from TypeScript React files.","package":"react-docgen-typescript","optional":false}],"imports":[{"note":"This package exports a default plugin function. Named imports are incorrect.","wrong":"import { remarkReactDocgen } from 'remark-mdx-react-docgen-typescript';","symbol":"remarkReactDocgen","correct":"import remarkReactDocgen from 'remark-mdx-react-docgen-typescript';"},{"note":"When using CommonJS `require` with an ESM default export, `.default` is necessary to access the plugin function.","wrong":"const remarkReactDocgen = require('remark-mdx-react-docgen-typescript');","symbol":"remarkReactDocgen (CommonJS)","correct":"const remarkReactDocgen = require('remark-mdx-react-docgen-typescript').default;"},{"note":"Import the `Options` type for type-safe configuration of the plugin.","symbol":"Options Type","correct":"import type { Options } from 'remark-mdx-react-docgen-typescript';"}],"quickstart":{"code":"import { readFile } from 'node:fs/promises';\nimport { compile } from '@mdx-js/mdx';\nimport remarkDirective from 'remark-directive';\nimport remarkReactDocgen from 'remark-mdx-react-docgen-typescript';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\n// Create a dummy Component.tsx for demonstration purposes\nconst componentCode = `\n/**\n * A simple example component.\n * @param greeting The greeting message.\n */\nexport function MyComponent({ greeting }: { greeting: string }) {\n  return <div>{greeting}, World!</div>;\n};\n`;\n\n// In a real scenario, this would be a file on disk.\n// For quickstart, we'll simulate the MDX and component content.\nconst mdxContent = `\n# My Component Documentation\n\nThis is an example of documenting MyComponent:\n\n::component-docs{file=\"./MyComponent.tsx\" greeting=\"Hello from MDX\"}\n`;\n\n// Simulate writing the component file (optional, for direct execution)\n// In a real project, MyComponent.tsx would exist alongside your MDX.\n// For this quickstart, we'll compile the MDX assuming MyComponent.tsx exists\n// or is mocked during compilation.\n\n// To run this, you'd typically have MyComponent.tsx in the same directory\n// as your MDX file. For a self-contained example:\n// await fs.promises.writeFile(path.join(__dirname, 'MyComponent.tsx'), componentCode);\n\nasync function compileMdxWithDocgen() {\n  try {\n    // Assuming 'MyComponent.tsx' is available where your MDX points.\n    // For this example, we'll configure rootDir to point to __dirname\n    // and ensure react-docgen-typescript can find the component.\n    const { contents } = await compile(mdxContent, {\n      jsx: true,\n      remarkPlugins: [\n        remarkDirective,\n        [remarkReactDocgen, { rootDir: __dirname, reactDocGenOptions: { tsConfigPath: path.join(__dirname, 'tsconfig.json') } }]\n      ],\n    });\n    console.log(contents);\n  } catch (error) {\n    console.error('MDX Compilation Error:', error);\n  }\n}\n\n// A tsconfig.json is often required for react-docgen-typescript\n// Example content for tsconfig.json:\n// {\"compilerOptions\": {\"jsx\": \"react\", \"module\": \"esnext\", \"target\": \"esnext\", \"esModuleInterop\": true, \"skipLibCheck\": true}}\n// Ensure it exists in __dirname for this example to work with a real file.\n\ncompileMdxWithDocgen();","lang":"typescript","description":"This quickstart demonstrates how to set up `remark-mdx-react-docgen-typescript` with `@mdx-js/mdx` to process an MDX file containing a `::component-docs` directive. It shows the necessary imports for `remark-directive` and the docgen plugin, then compiles the MDX, illustrating how component documentation is extracted and inserted as JSX props into a `<ComponentDocs>` component."},"warnings":[{"fix":"Review the official `v1.0.0` release notes and usage examples to identify any renamed imports, options, or configurations and update your `unified`/`remark` plugin chain accordingly.","message":"In `v1.0.0`, a breaking change was introduced due to a 'naming correction'. While specific details are not provided in the changelog excerpt, it likely involved changes to API surface, options names, or how the plugin is imported/configured, requiring users to update their setup.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `remarkDirective` is listed in your `remarkPlugins` array *before* `remarkReactDocgen` when configuring `@mdx-js/mdx` or `unified`.","message":"The plugin relies on `remark-directive` to parse the `::component-docs` syntax. If `remark-directive` is not included in the `remarkPlugins` array *before* `remark-mdx-react-docgen-typescript`, the custom directives will not be recognized, and the component documentation will not be extracted.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set the `rootDir` option in the plugin configuration to your project's root path (e.g., `process.cwd()`) and use `<rootDir>/path/to/component.tsx` in your MDX directives for project-relative paths.","message":"When using the `file` attribute in the `::component-docs` directive, paths are relative to the MDX file by default. If you need to specify paths relative to your project root, you must prefix them with `<rootDir>/` and configure the `rootDir` option in the plugin.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Provide a valid `tsConfigPath` within the `reactDocGenOptions` object, pointing to the `tsconfig.json` file relevant to your React components, or ensure your `tsconfig.json` is correctly configured for `react-docgen-typescript` to find it automatically.","message":"The `reactDocGenOptions` must be correctly configured, particularly `tsConfigPath`, if `react-docgen-typescript` struggles to parse your TypeScript components. Incorrect `tsconfig.json` paths or configurations can lead to incomplete or failed documentation extraction.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `remarkDirective` to your `remarkPlugins` array before `remarkReactDocgen`: `remarkPlugins: [remarkDirective, remarkReactDocgen]`.","cause":"The `::component-docs` directive was not properly parsed, often because `remark-directive` was not included or not placed before `remark-mdx-react-docgen-typescript` in the plugin chain.","error":"TypeError: Cannot read properties of undefined (reading 'type')"},{"fix":"Verify the `file` path in your MDX directive is correct relative to the MDX file or correctly configured with `<rootDir>/` and the `rootDir` plugin option. Ensure the target file exports a valid React component.","cause":"The `file` path specified in the `::component-docs` directive is incorrect, or `react-docgen-typescript` failed to identify a React component within the specified file. This can also happen if the `rootDir` option is not correctly set for paths using `<rootDir>/`.","error":"Error: Could not find any component in file:"},{"fix":"Check your `reactDocGenOptions.tsConfigPath` to ensure it points to a valid `tsconfig.json`. Verify the `tsconfig.json` includes the component files and has appropriate compiler options (e.g., `jsx`). Ensure the TypeScript component file is valid and compilable.","cause":"Likely an issue with `react-docgen-typescript`'s ability to process the TypeScript component file. This often points to problems with the `tsconfig.json` configuration or the TypeScript code itself.","error":"Error: Could not parse file with react-docgen-typescript:"}],"ecosystem":"npm"}