{"id":20914784,"url":"https://github.com/noahbuscher/react-tsdoc","last_synced_at":"2025-05-13T10:31:49.429Z","repository":{"id":57346826,"uuid":"443686719","full_name":"noahbuscher/react-tsdoc","owner":"noahbuscher","description":"Document Typescript React components with TSDoc and export Storybook-friendly JSON 🤖","archived":false,"fork":false,"pushed_at":"2022-01-24T17:35:49.000Z","size":856,"stargazers_count":19,"open_issues_count":4,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-09T05:43:04.915Z","etag":null,"topics":["documentation","react","storybook","tsdoc","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noahbuscher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-02T05:11:41.000Z","updated_at":"2024-10-11T11:00:36.000Z","dependencies_parsed_at":"2022-08-31T22:00:33.775Z","dependency_job_id":null,"html_url":"https://github.com/noahbuscher/react-tsdoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbuscher%2Freact-tsdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbuscher%2Freact-tsdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbuscher%2Freact-tsdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahbuscher%2Freact-tsdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noahbuscher","download_url":"https://codeload.github.com/noahbuscher/react-tsdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225198465,"owners_count":17436902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","react","storybook","tsdoc","typescript"],"created_at":"2024-11-18T16:10:56.493Z","updated_at":"2024-11-18T16:10:57.028Z","avatar_url":"https://github.com/noahbuscher.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./logo.png\" width=\"200px\"/\u003e\u003cbr/\u003e\n  \u003ci\u003e:sparkles: Document React components with \u003ccode\u003e@prop\u003c/code\u003e :sparkles:\u003c/i\u003e\n\u003c/div\u003e\n\n\n# react-tsdoc 🤖\n\nreact-tsdoc is an tool to extract information from React Typescript component\nfiles with [TSDoc](https://tsdoc.org) for documentation generation that\nelaborates on the TSDoc standard. Just use `@prop`!\n\n\u003e Similar to react-docgen, react-tsdoc is a low level tool to extract information\nabout React components. Use [react-tsdoc-loader](https://github.com/noahbuscher/react-tsdoc-loader)\nto inject the docs into Storybook.\n\n**Wouldn't it be nice if instead of doing this...**\n\n```tsx\n/**\n * Nice button\n */\nconst Button = ({\n\tdisabled,\n\tlabel,\n\tonClick\n}: {\n\t/**\n\t * Disables the button\n\t */\n\tdisabled: boolean\n\t/**\n\t * Label for the button\n\t */\n\tlabel: string\n\t/**\n\t * Fired when button clicked\n\t */\n\tonClick: (...) =\u003e {}\n}) =\u003e ();\n```\n\n**You could do this 👇 and _still_ have Storybook pick up the prop descriptions?**\n\n```jsx\n/**\n * Nice button\n *\n * @prop disabled - Disables the button\n * @prop label - Label for the button\n * @prop onClick - Fired when button clicked\n */\nconst Button = ({\n\tdisabled,\n\tlabel,\n\tonClick\n}: {\n\tdisabled: boolean\n\tlabel: string\n\tonClick: (...) =\u003e {}\n}) =\u003e ();\n\n```\n\n**That's where react-tsdoc comes in! It automatically generates documentation from the\nTSDoc comment's `@prop`s while also still passing through all the other goodies you also\nwant to see, such as if a prop is required, types, default values, and more!**\n\n## Install\n\nTo install `react-tsdoc` just run:\n\n```\nnpm i -g react-tsdoc\n```\n\nAnd you can run the parser like:\n\n```\nreact-tsdoc ./src/components --output ./docs/output.json\n```\n\n## How do I use this with Storybook?\n\nThis tool just create JSON blobs with the documentation information. To use this with Storybook\nyou'll need to use the Webpack loader to inject this information into your story's components.\n\nUse [react-tsdoc-loader](https://github.com/noahbuscher/react-tsdoc-loader) to inject the docs\ninto Storybook.\n\n## Why `@prop`?\n\nBecause it looks nicer! I personally perfer seeing the descriptions for all of my component's\nprops right at the top so I can get all of the information I need right at a glance.\n\n## Why TSDoc instead of JSDoc?\n\nGreat question! Part of the beauty of Typescript is that you explicitely set types,\nso why would you want to duplicate those in your docs? [TSDoc](https://tsdoc.org)\ndoes away with that so you only need to call out your prop name and add a description. Easy!\n\n## Output\n\nHere's an example component with the associated parser output...\n\n**Input:**\n\n```tsx\n/**\n * Button\n *\n * @prop disabled - Sets if field is disabled\n * @prop label - Sets the button text\n */\nconst Button = ({\n\tdisabled = false,\n\tlabel\n}: {\n\tdisabled?: boolean\n\tlabel: string\n}) =\u003e {\n\treturn (\n\t\t\u003cbutton disabled={disabled}\u003e\n\t\t\t{label}\n\t\t\u003c/button\u003e\n\t)\n};\n```\n\n**Output:**\n\n```json\n{\n  \"description\": \"Button\",\n  \"props\": {\n    \"disabled\": {\n      \"description\": \"Sets if field is disabled\",\n      \"required\": false,\n      \"tsType\": {\n        \"name\": \"boolean\"\n      },\n      \"defaultValue\": {\n        \"value\": \"false\",\n        \"computed\": false\n      }\n    },\n    \"label\": {\n      \"description\": \"Sets the button text\",\n      \"required\": true,\n      \"tsType\": {\n        \"name\": \"string\"\n      }\n    }\n  }\n}\n```\n\n## Adding to `tsdoc.json`\n\nAdding support for the `@prop` tag to your TSDoc config is easy! This allows your\n`eslint-plugin-tsdoc` to properly parse `@prop`. Create a `tsdoc.json` if you don't\nalready have one and add this to it:\n\n```json\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json\",\n  \"tagDefinitions\": [\n    {\n      \"tagName\": \"@prop\",\n      \"syntaxKind\": \"block\"\n    }\n  ]\n}\n```\n\n## Why another docgen?\n\nThough `react-docgen`, `typedoc`, and `react-docgen-typescript` are all wonderful\ntools, defining props can be a challenge, especially if you are destructuring props.\n\nAs [Shilman](https://gist.github.com/shilman)\nof Storybook noted in\n[this Gist](https://gist.github.com/shilman/036313ffa3af52ca986b375d90ea46b0),\nStorybook plans to adopt `react-docgen` for SB7, however `react-docgen` is based\non an outdated Doc parser (`doctrine`) and does _not_ support the TSDoc standard.\n\nI have found that interface documentation can be rather cumbersome and being able\nto see what each respective prop is used for at a glance is extremely handy.\n\nUltimately, this is just an excuse for me to play around with ASTs, but I hope\nothers find some use in this project.\n\n## Supported Types\n\n- [x] Simple (`foo: string`, `bar: boolean`)\n- [x] Literals (`foo: 'bar'`)\n- [x] Tuples (`foo: [string, number]`)\n- [x] Unions (`foo: string | boolean`)\n- [x] Typed arrays (`foo: string[]`)\n- [x] Object signatures (`{ foo: string}`)\n- [x] Index signatures (`[foo: string]: string`)\n- [x] Function signatures (`foo: (x: string) =\u003e void`)\n- [ ] Intersect (`foo: string \u0026 number`)\n- [ ] Nullable modifier (`foo: ?number`)\n- [ ] Typed classes (`foo: Class\u003cbar\u003e`)\n\n_Extended support coming soon._\n\n## Development\n\nI've heavily commented a lot of the functions as this has been an AST learning\nexperience for me, and I hope others find it easy to understand and contribute.\n\nTo build, just run:\n\n```\nnpm install \u0026\u0026 npm run build\n```\n\nThis will build the `./lib` folder and then you can execute the CLI from the `/bin`\ndirectory, like this:\n\n```\nbin/react-tsdoc.js ./src/components ./output.json \u0026\u0026 cat ./output.json\n```\n\nTo run the tests:\n\n```\nnpm run test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoahbuscher%2Freact-tsdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoahbuscher%2Freact-tsdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoahbuscher%2Freact-tsdoc/lists"}