├── .nvmrc ├── .husky ├── .gitignore ├── pre-commit └── commit-msg ├── .eslintignore ├── .npmrc ├── .prettierrc ├── src ├── hooks │ ├── index.ts │ └── useDynamicImport.ts └── index.ts ├── .lintstagedrc ├── commitlint.config.js ├── scripts └── files.sh ├── .editorconfig ├── .eslintrc ├── tsconfig.json ├── .vscode └── settings.json ├── .github └── workflows │ ├── on_push.yml │ └── release.yml ├── .releaserc.json ├── LICENSE ├── .gitignore ├── package.json ├── CHANGELOG.md └── README.md /.nvmrc: -------------------------------------------------------------------------------- 1 | lts 2 | -------------------------------------------------------------------------------- /.husky/.gitignore: -------------------------------------------------------------------------------- 1 | _ 2 | -------------------------------------------------------------------------------- /.eslintignore: -------------------------------------------------------------------------------- 1 | package.json 2 | -------------------------------------------------------------------------------- /.husky/pre-commit: -------------------------------------------------------------------------------- 1 | pnpm lint-staged 2 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | enable-pre-post-scripts=true 2 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | "@djthoms/prettier-config" 2 | -------------------------------------------------------------------------------- /.husky/commit-msg: -------------------------------------------------------------------------------- 1 | npx --no -- commitlint --edit "${1}" 2 | -------------------------------------------------------------------------------- /src/hooks/index.ts: -------------------------------------------------------------------------------- 1 | export * from "./useDynamicImport"; 2 | -------------------------------------------------------------------------------- /.lintstagedrc: -------------------------------------------------------------------------------- 1 | { 2 | "*.{ts,tsx,js,jsx}": [ 3 | "prettier --write", 4 | "eslint --fix" 5 | ], 6 | "*.{md,yml,yaml,json}": "prettier --write" 7 | } 8 | -------------------------------------------------------------------------------- /commitlint.config.js: -------------------------------------------------------------------------------- 1 | /* eslint-disable no-undef */ 2 | // eslint-disable-next-line id-denylist 3 | module.exports = { extends: ['@commitlint/config-conventional'] }; 4 | -------------------------------------------------------------------------------- /scripts/files.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | set -e 3 | 4 | readonly SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &> /dev/null && pwd) 5 | cd $SCRIPT_DIR/.. 6 | pnpm glob 'src/**/*.{ts,tsx}' 7 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = space 5 | indent_size = 2 6 | charset = utf-8 7 | trim_trailing_whitespace = true 8 | insert_final_newline = true 9 | end_of_line = lf 10 | -------------------------------------------------------------------------------- /.eslintrc: -------------------------------------------------------------------------------- 1 | { 2 | "extends": [ 3 | "@djthoms/eslint-config", 4 | "@djthoms/eslint-config/typescript", 5 | "@djthoms/eslint-config/react", 6 | "@djthoms/eslint-config/react-typescript", 7 | ], 8 | "parserOptions": { 9 | "project": "./tsconfig.json", 10 | }, 11 | "rules": { 12 | "@typescript-eslint/no-explicit-any": "off", 13 | "@typescript-eslint/no-unsafe-argument": "warn", 14 | }, 15 | } 16 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "esModuleInterop": true, 4 | "declaration": true, 5 | "declarationMap": true, 6 | "emitDeclarationOnly": true, 7 | "allowSyntheticDefaultImports": true, 8 | "skipLibCheck": true, 9 | "declarationDir": "dist/types", 10 | "moduleResolution": "Bundler", 11 | "target": "ES2022", 12 | "module": "ESNext", 13 | "strict": true, 14 | "resolveJsonModule": true 15 | }, 16 | "include": ["src"] 17 | } 18 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "prettier.enable": true, 3 | "eslint.validate": [ 4 | "javascript", 5 | "javascriptreact", 6 | "typescript", 7 | "typescriptreact", 8 | "json", 9 | "jsonc" 10 | ], 11 | "[typescript]": { 12 | "editor.defaultFormatter": "esbenp.prettier-vscode" 13 | }, 14 | "[typescriptreact]": { 15 | "editor.defaultFormatter": "esbenp.prettier-vscode" 16 | }, 17 | "[jsonc]": { 18 | "editor.defaultFormatter": "esbenp.prettier-vscode" 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /.github/workflows/on_push.yml: -------------------------------------------------------------------------------- 1 | name: Push 2 | on: 3 | push: 4 | branches-ignore: 5 | - main 6 | jobs: 7 | release: 8 | name: Build & Test 9 | runs-on: ubuntu-latest 10 | steps: 11 | - name: Checkout 12 | uses: actions/checkout@v4 13 | - uses: pnpm/action-setup@v4 14 | with: 15 | version: 9 16 | - name: Setup Node.js 17 | uses: actions/setup-node@v4 18 | with: 19 | node-version: 22 20 | cache: pnpm 21 | - name: Install, Lint, Test 22 | run: | 23 | pnpm install --frozen-lockfile 24 | pnpm lint 25 | pnpm build 26 | -------------------------------------------------------------------------------- /src/hooks/useDynamicImport.ts: -------------------------------------------------------------------------------- 1 | import { useEffect, useState } from "react"; 2 | 3 | export const useDynamicImport = = any>( 4 | name: string, 5 | ): T => { 6 | const [props, setProps] = useState({} as T); 7 | 8 | useEffect(() => { 9 | let resolved = false; 10 | 11 | import(`@docgen/${name}.json`) 12 | .then((mod: { default: T }) => { 13 | if (!resolved) { 14 | resolved = true; 15 | setProps(mod.default); 16 | } 17 | }) 18 | .catch(console.error); 19 | 20 | return () => { 21 | resolved = true; 22 | }; 23 | }, [name]); 24 | 25 | return props; 26 | }; 27 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | on: 3 | push: 4 | branches: 5 | - main 6 | workflow_dispatch: 7 | jobs: 8 | release: 9 | name: Release 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Checkout 13 | uses: actions/checkout@v4 14 | - uses: pnpm/action-setup@v4 15 | with: 16 | version: 9 17 | - name: Setup Node.js 18 | uses: actions/setup-node@v4 19 | with: 20 | node-version: 22 21 | cache: pnpm 22 | - name: Install dependencies 23 | run: | 24 | pnpm install --frozen-lockfile 25 | pnpm lint 26 | pnpm build 27 | - name: Release 28 | env: 29 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 30 | NPM_TOKEN: ${{ secrets.NPM_TOKEN }} 31 | run: pnpm semantic-release 32 | -------------------------------------------------------------------------------- /.releaserc.json: -------------------------------------------------------------------------------- 1 | { 2 | "branches": ["main"], 3 | "plugins": [ 4 | "@semantic-release/commit-analyzer", 5 | [ 6 | "@semantic-release/release-notes-generator", 7 | { 8 | "preset": "conventionalcommits", 9 | "parserOpts": { 10 | "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"] 11 | }, 12 | "writerOpts": { 13 | "commitsSort": ["subject", "scope"] 14 | } 15 | } 16 | ], 17 | [ 18 | "@semantic-release/changelog", 19 | { 20 | "changelogFile": "CHANGELOG.md" 21 | } 22 | ], 23 | "@semantic-release/github", 24 | "@semantic-release/npm", 25 | [ 26 | "@semantic-release/git", 27 | { 28 | "assets": ["package.json", "package-lock.json", "CHANGELOG.md"], 29 | "message": "chore(release): ${nextRelease.version} [skip ci]" 30 | } 31 | ] 32 | ] 33 | } 34 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Dennis Thompson 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | 9 | # Diagnostic reports (https://nodejs.org/api/report.html) 10 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 11 | 12 | # Runtime data 13 | pids 14 | *.pid 15 | *.seed 16 | *.pid.lock 17 | 18 | # Directory for instrumented libs generated by jscoverage/JSCover 19 | lib-cov 20 | 21 | # Coverage directory used by tools like istanbul 22 | coverage 23 | *.lcov 24 | 25 | # nyc test coverage 26 | .nyc_output 27 | 28 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 29 | .grunt 30 | 31 | # Bower dependency directory (https://bower.io/) 32 | bower_components 33 | 34 | # node-waf configuration 35 | .lock-wscript 36 | 37 | # Compiled binary addons (https://nodejs.org/api/addons.html) 38 | build/Release 39 | 40 | # Dependency directories 41 | node_modules/ 42 | jspm_packages/ 43 | 44 | # TypeScript v1 declaration files 45 | typings/ 46 | 47 | # TypeScript cache 48 | *.tsbuildinfo 49 | 50 | # Optional npm cache directory 51 | .npm 52 | 53 | # Optional eslint cache 54 | .eslintcache 55 | 56 | # Microbundle cache 57 | .rpt2_cache/ 58 | .rts2_cache_cjs/ 59 | .rts2_cache_es/ 60 | .rts2_cache_umd/ 61 | 62 | # Optional REPL history 63 | .node_repl_history 64 | 65 | # Output of 'npm pack' 66 | *.tgz 67 | 68 | # Yarn Integrity file 69 | .yarn-integrity 70 | 71 | # dotenv environment variables file 72 | .env 73 | .env.test 74 | 75 | # parcel-bundler cache (https://parceljs.org/) 76 | .cache 77 | 78 | # Next.js build output 79 | .next 80 | 81 | # Nuxt.js build / generate output 82 | .nuxt 83 | dist 84 | 85 | # Gatsby files 86 | .cache/ 87 | # Comment in the public line in if your project uses Gatsby and *not* Next.js 88 | # https://nextjs.org/blog/next-9-1#public-directory-support 89 | # public 90 | 91 | # vuepress build output 92 | .vuepress/dist 93 | 94 | # Serverless directories 95 | .serverless/ 96 | 97 | # FuseBox cache 98 | .fusebox/ 99 | 100 | # DynamoDB Local files 101 | .dynamodb/ 102 | 103 | # TernJS port file 104 | .tern-port 105 | 106 | # pika 107 | pkg/ 108 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "docusaurus-plugin-react-docgen-typescript", 3 | "version": "1.3.0", 4 | "description": "A small plugin that integrates react-docgen-typescript with docusaurus 2.x", 5 | "keywords": [ 6 | "docusaurus", 7 | "docusaurus-plugin", 8 | "docusaurus2-plugin", 9 | "react-docgen", 10 | "react-docgen-typescript", 11 | "typescript" 12 | ], 13 | "repository": { 14 | "type": "git", 15 | "url": "https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript" 16 | }, 17 | "license": "MIT", 18 | "author": "Dennis Thompson", 19 | "main": "./dist/cjs/index.js", 20 | "module": "./dist/esm/index.mjs", 21 | "types": "./dist/types/index.d.ts", 22 | "exports": { 23 | ".": { 24 | "require": { 25 | "types": "./dist/cjs/index.d.ts", 26 | "default": "./dist/cjs/index.js" 27 | }, 28 | "import": { 29 | "types": "./dist/esm/index.d.mts", 30 | "default": "./dist/esm/index.mjs" 31 | } 32 | }, 33 | "./useDynamicImport": { 34 | "require": { 35 | "types": "./dist/cjs/hooks/useDynamicImport.d.ts", 36 | "default": "./dist/cjs/hooks/useDynamicImport.js" 37 | }, 38 | "import": { 39 | "types": "./dist/esm/hooks/useDynamicImport.d.mts", 40 | "default": "./dist/esm/hooks/useDynamicImport.mjs" 41 | } 42 | } 43 | }, 44 | "files": [ 45 | "dist" 46 | ], 47 | "scripts": { 48 | "test": "echo \"Error: no test specified\" && exit 0", 49 | "lint": "eslint src --ext=ts,tsx,js,jsx,json", 50 | "prebuild": "rm -rf dist", 51 | "build": "npm-run-all -p build:*", 52 | "build:esm": "tsup --sourcemap --format esm --target es2022 --dts -d dist/esm `./scripts/files.sh`", 53 | "build:cjs": "tsup --sourcemap --format cjs --target es2020 --dts -d dist/cjs `./scripts/files.sh`", 54 | "build:types": "tsc -p .", 55 | "prepare": "is-ci || husky install" 56 | }, 57 | "dependencies": { 58 | "glob": "^11.0.0" 59 | }, 60 | "devDependencies": { 61 | "@arethetypeswrong/cli": "^0.17.2", 62 | "@commitlint/cli": "^19.6.1", 63 | "@commitlint/config-conventional": "^19.6.0", 64 | "@djthoms/eslint-config": "^6.4.2", 65 | "@djthoms/prettier-config": "^4.4.1", 66 | "@docusaurus/types": "^3.7.0", 67 | "@semantic-release/changelog": "^6.0.3", 68 | "@semantic-release/git": "^10.0.1", 69 | "@types/node": "^22.10.5", 70 | "@types/react": "^18.3.18", 71 | "husky": "^9.1.7", 72 | "is-ci": "^3.0.1", 73 | "lint-staged": "^15.3.0", 74 | "npm-run-all": "^4.1.5", 75 | "react": "^18.3.1", 76 | "react-docgen-typescript": "^2.2.2", 77 | "semantic-release": "^24.2.1", 78 | "tsup": "^8.3.5", 79 | "typescript": "^5.7.2" 80 | }, 81 | "peerDependencies": { 82 | "react": ">=16.8.0", 83 | "react-docgen-typescript": "^2.0.0" 84 | }, 85 | "publishConfig": { 86 | "access": "public" 87 | } 88 | } 89 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## [1.2.1](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/compare/v1.2.0...v1.2.1) (2024-08-29) 2 | 3 | 4 | ### Bug Fixes 5 | 6 | * ensure duplicate components are written to unique files ([#23](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/issues/23)) ([60d9da3](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/60d9da3e36bdc28d4b25b633877f94385c813cc3)) 7 | 8 | ## [1.2.0](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/compare/v1.1.0...v1.2.0) (2024-05-19) 9 | 10 | 11 | ### Features 12 | 13 | * move to tsup for transpiling to support ESM ([#22](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/issues/22)) ([6f2f64f](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/6f2f64f49ffa078dfe62878820ba6c161141e159)) 14 | 15 | ## [1.1.0](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/compare/v1.0.1...v1.1.0) (2023-01-25) 16 | 17 | ### Features 18 | 19 | - bleh commit to get semantic-release behaving 20 | ([122c13b](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/122c13bbbb7064fb2de15e91ee393eddae1be8c4)) 21 | 22 | ### Bug Fixes 23 | 24 | - convert JS Array to multiple Glob matching pattern 25 | ([#15](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/issues/15)) 26 | ([ce64361](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/ce643616d91495a9d6f1274ff2558a205b39f045)) 27 | - export types and update deps 28 | ([6077208](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/60772081af0d20b3ae8fe5f98e0961d4eb2928ef)) 29 | - remove malformed glob syntax 30 | ([c97c5a6](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/c97c5a630146a517a4c871f1a39ce09f4ac491b4)) 31 | 32 | ## [1.0.2](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/compare/v1.0.1...v1.0.2) (2023-01-25) 33 | 34 | ### Bug Fixes 35 | 36 | - convert JS Array to multiple Glob matching pattern 37 | ([#15](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/issues/15)) 38 | ([ce64361](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/ce643616d91495a9d6f1274ff2558a205b39f045)) 39 | - export types and update deps 40 | ([6077208](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/60772081af0d20b3ae8fe5f98e0961d4eb2928ef)) 41 | - remove malformed glob syntax 42 | ([c97c5a6](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/c97c5a630146a517a4c871f1a39ce09f4ac491b4)) 43 | 44 | ## [1.0.1](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/compare/v1.0.0...v1.0.1) (2022-06-28) 45 | 46 | ### Bug Fixes 47 | 48 | - fix workflow 49 | ([9fd7108](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/9fd7108f4c7e23ed8b5a34194e1722aa959b7dc4)) 50 | 51 | ## [1.0.0](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/compare/v0.1.0...v1.0.0) (2022-06-20) 52 | 53 | ### ⚠ BREAKING CHANGES 54 | 55 | - - upgrade to react-docgen-typescript v2 56 | 57 | * rework exports 58 | 59 | ### Features 60 | 61 | - upgrade to react-docgen-typescript v2 62 | ([d34c6e2](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/d34c6e27a247f9d637fe6936b47070a22c2d10d1)) 63 | 64 | ### Bug Fixes 65 | 66 | - **readme:** useDynamicImport may return null 67 | ([#3](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/issues/3)) 68 | ([#4](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/issues/4)) 69 | ([3278ff2](https://github.com/atomicpages/docusaurus-plugin-react-docgen-typescript/commit/3278ff2dac5d23bcd39ef23575bbf0dea94eccc3)) 70 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | /* eslint-disable @typescript-eslint/unbound-method */ 2 | import path from "node:path"; 3 | 4 | import type { 5 | ParserOptions, 6 | ComponentDoc, 7 | FileParser, 8 | } from "react-docgen-typescript"; 9 | import { 10 | withCustomConfig, 11 | withCompilerOptions, 12 | withDefaultConfig, 13 | } from "react-docgen-typescript"; 14 | 15 | import type { Plugin, DocusaurusContext, RouteConfig } from "@docusaurus/types"; 16 | import { glob } from "glob"; 17 | import type { CompilerOptions } from "typescript"; 18 | 19 | type Route = Pick; 20 | 21 | type Union = 22 | | { 23 | global?: undefined | false; 24 | route: Route; 25 | } 26 | | { 27 | global: boolean; 28 | route?: Route; 29 | }; 30 | 31 | export type Options = Union & { 32 | src: string | string[]; 33 | ignore?: string[]; 34 | tsConfig?: string; 35 | compilerOptions?: CompilerOptions; 36 | parserOptions?: ParserOptions; 37 | globOptions: null; 38 | }; 39 | 40 | function getParser( 41 | config?: Options["tsConfig"], 42 | options?: Options["compilerOptions"], 43 | parserOptions?: Options["parserOptions"], 44 | ): FileParser["parse"] { 45 | if (config) { 46 | return withCustomConfig(config, parserOptions ?? {}).parse; 47 | } else if (options) { 48 | return withCompilerOptions(options, parserOptions).parse; 49 | } 50 | 51 | return withDefaultConfig(parserOptions).parse; 52 | } 53 | 54 | export default function plugin( 55 | context: DocusaurusContext, 56 | { 57 | src, 58 | ignore, 59 | global = false, 60 | route, 61 | tsConfig, 62 | compilerOptions, 63 | parserOptions, 64 | }: Options, 65 | ): Plugin { 66 | return { 67 | name: "docusaurus-plugin-react-docgen-typescript", 68 | async loadContent() { 69 | return getParser( 70 | tsConfig, 71 | compilerOptions, 72 | parserOptions, 73 | )( 74 | await glob(src, { 75 | absolute: true, 76 | ignore, 77 | }), 78 | ); 79 | }, 80 | configureWebpack(config) { 81 | return { 82 | resolve: { 83 | alias: { 84 | "@docgen": path.join( 85 | // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access 86 | (config.resolve!.alias as any)["@generated"], 87 | "docusaurus-plugin-react-docgen-typescript", 88 | "default", 89 | ), 90 | }, 91 | }, 92 | }; 93 | }, 94 | async contentLoaded({ content, actions }): Promise { 95 | const { createData, setGlobalData, addRoute } = actions; 96 | 97 | if (global) { 98 | console.warn( 99 | "Using global data can potentially slow down your entire app. Use with care ❤️", 100 | ); 101 | 102 | setGlobalData(content); 103 | } else if (route) { 104 | addRoute({ 105 | ...route, 106 | modules: { 107 | docgen: await createData("docgen.json", JSON.stringify(content)), 108 | }, 109 | }); 110 | } else { 111 | const toProcess = content.reduce< 112 | [ 113 | Record, 114 | { fileName: string; component: ComponentDoc }[], 115 | ] 116 | >( 117 | ([processed, components], component) => { 118 | const componentName = component.displayName; 119 | let fileName = componentName; 120 | const alreadyProcessed = processed[componentName]; 121 | if (alreadyProcessed && alreadyProcessed.length > 0) { 122 | console.warn( 123 | `Duplicate component '${componentName}' found (existing: 124 | ${alreadyProcessed[alreadyProcessed.length - 1]})`, 125 | ); 126 | 127 | fileName += `${alreadyProcessed.length}`; 128 | console.warn( 129 | `'${component.filePath}' will be written to '${fileName}.json'`, 130 | ); 131 | } 132 | return [ 133 | { 134 | ...processed, 135 | [componentName]: [ 136 | ...(alreadyProcessed || []), 137 | component.filePath, 138 | ], 139 | }, 140 | [...components, { fileName, component }], 141 | ]; 142 | }, 143 | [{}, []], 144 | ); 145 | toProcess[1].forEach(({ fileName, component }) => { 146 | void createData(`${fileName}.json`, JSON.stringify(component.props)); 147 | }); 148 | } 149 | }, 150 | }; 151 | } 152 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Docusaurus Plugin `react-docgen-typescript` 2 | 3 | A Docusaurus 2.x plugin that help generate and consume auto-generated docs from 4 | `react-docgen-typescript`. 5 | 6 | ## Installation 7 | 8 | Grab from NPM and install along with `react-docgen-typescript`: 9 | 10 | ```sh 11 | npm i --save-dev docusaurus-plugin-react-docgen-typescript react-docgen-typescript 12 | ``` 13 | 14 | ## Usage 15 | 16 | Inside your `docusaurus.config.js` add to the `plugins` field and configure with 17 | the `src` option with full glob support :+1:. 18 | 19 | ```js 20 | module.exports = { 21 | // ... 22 | plugins: [ 23 | [ 24 | "docusaurus-plugin-react-docgen-typescript", 25 | /** @type {import('docusaurus-plugin-react-docgen-typescript').Options} */ 26 | { 27 | // pass in a single string or an array of strings 28 | src: ["path/to/**/*.tsx"], 29 | ignore: ["path/to/**/*test.*"], 30 | parserOptions: { 31 | // pass parserOptions to react-docgen-typescript 32 | // here is a good starting point which filters out all 33 | // types from react 34 | propFilter: (prop, component) => { 35 | if (prop.parent) { 36 | return !prop.parent.fileName.includes("@types/react"); 37 | } 38 | 39 | return true; 40 | }, 41 | }, 42 | }, 43 | ], 44 | ], 45 | }; 46 | ``` 47 | 48 | Any pattern supported by [`fast-glob`](https://github.com/mrmlnc/fast-glob) is 49 | allowed here (including negations). 50 | 51 | `src` paths are relative to the location of your `docusaurus.config.js`. For 52 | example, if you had a directory structure like: 53 | 54 | ``` 55 | . 56 | ├── LICENSE 57 | ├── README.md 58 | ├── package.json 59 | ├── src 60 | ... 61 | ├── website 62 | │ ├── README.md 63 | │ ├── babel.config.js 64 | │ ├── blog 65 | │ ├── docs 66 | │ ├── docusaurus.config.js 67 | | ... 68 | │ ├── src 69 | │ └── yarn.lock 70 | └── yarn.lock 71 | ``` 72 | 73 | Then to document all of your JSX components in your `src/` directory, you would 74 | use this path: `../src/**/*.jsx`. 75 | 76 | ## Reading Annotations 77 | 78 | Using the default settings, annotations are stored inside of the `.docusaurus` 79 | directory. The `@docgen` alias is set to ensure stable access to these files. 80 | 81 | ### Build a Prop Table 82 | 83 | Most of the time props will want to be shown as API information to a particular 84 | component. For convenience, we can use a simple hook from this package to 85 | dynamically import `.json` files: 86 | 87 | ```tsx 88 | import { useDynamicImport } from "docusaurus-plugin-react-docgen-typescript/useDynamicImport"; 89 | 90 | type MyProps = { 91 | /* ... */ 92 | }; 93 | 94 | export const PropTable = ({ name }) => { 95 | const props = useDynamicImport(name); 96 | 97 | if (!props) { 98 | return null; 99 | } 100 | 101 | return ( 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | {Object.keys(props).map((key) => { 114 | return ( 115 | 116 | 119 | 122 | 127 | 128 | 129 | 130 | ); 131 | })} 132 | 133 |
NameTypeDefault ValueRequiredDescription
117 | {key} 118 | 120 | {props[key].type?.name} 121 | 123 | {props[key].defaultValue && ( 124 | {props[key].defaultValue.value} 125 | )} 126 | {props[key].required ? "Yes" : "No"}{props[key].description}
134 | ); 135 | }; 136 | ``` 137 | 138 | **N.b.** If you use `global: true`, then you must use the 139 | [`useGlobalData` hook](https://docusaurus.io/docs/docusaurus-core#useGlobalData) 140 | to access the docgen data. You cannot use `useDynamicImport`. 141 | 142 | ## Options 143 | 144 | | Name | Type | Required | Description | 145 | | ----------------- | ---------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | 146 | | `src` | `string` \| `string[]` | Yes | Tell `react-docgen` where to look for source files. | 147 | | `global` | `boolean` | No | Store results so they're [globally accessible](https://v2.docusaurus.io/docs/docusaurus-core#useplugindatapluginname-string-pluginid-string) in docusaurus | 148 | | `route` | [`RouteConfig`](https://v2.docusaurus.io/docs/lifecycle-apis#actions) | No | Makes docgen results accessible at the specified URL. Note `modules` cannot be overridden. | 149 | | `tsConfig` | `string` | No | Specify the path to your custom tsconfig file (note that in most cases the default config is sufficient) | 150 | | `compilerOptions` | `CompilerOptions` | No | Pass custom ts compiler options in lieu of of a custom `tsConfig` | 151 | | `parserOptions` | [`ParserOptions`](https://github.com/styleguidist/react-docgen-typescript#options) | No | Options passed to `react-docgen-typescript` | 152 | --------------------------------------------------------------------------------