styleguidist/react-docgen-typescriptPublic

NotificationsYou must be signed in to change notification settings
Fork257
Star1.3k

A simple parser for react properties defined in typescript instead of propTypes.

License

MIT license

1.3k stars 257 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 603 Commits
.github/workflows		.github/workflows
examples		examples
src		src
.gitignore		.gitignore
.lintstagedrc		.lintstagedrc
.npmignore		.npmignore
.prettierrc		.prettierrc
LICENSE.md		LICENSE.md
README.md		README.md
lint.json		lint.json
package-lock.json		package-lock.json
package.json		package.json
stylesheet-example-column.png		stylesheet-example-column.png
stylesheet-example-grid.png		stylesheet-example-grid.png
tsconfig.json		tsconfig.json

Repository files navigation

react-docgen-typescript

A simple parser for React properties defined in TypeScript instead of propTypes.

It can be used withReact Styleguidist.

Installation

npm install --save-dev react-docgen-typescript

Usage

To parse a file for docgen information use theparse function.

constdocgen=require("react-docgen-typescript");constoptions={savePropValueAsString:true,};// Parse a file for docgen infodocgen.parse("./path/to/component",options);

If you want to customize the typescript configuration or docgen options, this package exports a variety of ways to create custom parsers.

constdocgen=require("react-docgen-typescript");// Create a parser with the default typescript config and custom docgen optionsconstcustomParser=docgen.withDefaultConfig(options);constdocs=customParser.parse("./path/to/component");// Create a parser with the custom typescript and custom docgen optionsconstcustomCompilerOptionsParser=docgen.withCompilerOptions({esModuleInterop:true},options);// Create a parser with using your typescript configconsttsConfigParser=docgen.withCustomConfig("./tsconfig.json",{savePropValueAsString:true,});

React Styleguidist integration

Include following line in yourstyleguide.config.js:

module.exports={propsParser:require("react-docgen-typescript").withDefaultConfig([parserOptions,]).parse,};

or if you want to use custom tsconfig file

module.exports={propsParser:require("react-docgen-typescript").withCustomConfig("./tsconfig.json",[parserOptions]).parse,};

Options

`propFilter`

ThepropFilter option allows you to omit certain props from documentation generation.

You can either provide and object with some of our pre-configured filters:

interfaceFilterOptions{skipPropsWithName?:string[]|string;skipPropsWithoutDoc?:boolean;}constoptions={propFilter:{skipPropsWithName:['as','id'];    skipPropsWithoutDoc:true;}}

If you do not want to print out all the HTML attributes of a component typed like the following:

constMyComponent:React.FC<React.HTMLAttributes<HTMLDivElement>>=()...

you can provide apropFilter function and do the filtering logic yourself.

typePropFilter=(prop:PropItem,component:Component)=>boolean;constoptions={propFilter:(prop:PropItem,component:Component)=>{if(prop.declarations!==undefined&&prop.declarations.length>0){consthasPropAdditionalDescription=prop.declarations.find((declaration)=>{return!declaration.fileName.includes("node_modules");});returnBoolean(hasPropAdditionalDescription);}returntrue;},};

Note:children without a doc comment will not be documented.

`componentNameResolver`

(exp:ts.Symbol,source:ts.SourceFile)=>string|undefined|null|false;

If a string is returned, then the component will use that name. Else it will fallback to the default logic of parser.

`shouldExtractLiteralValuesFromEnum`: boolean

If set to true, string enums and unions will be converted to docgen enum format. Useful if you use Storybook and want to generate knobs automatically usingaddon-smart-knobs.

`shouldExtractValuesFromUnion`: boolean

If set to true, every unions will be converted to docgen enum format.

`shouldSortUnions`: boolean

When used in combination withshouldExtractValuesFromUnion orshouldExtractLiteralValuesFromEnum, sorts union members in string-sort order when set to true. This is useful for ensuring the same order of members every time.

`skipChildrenPropWithoutDoc`: boolean (default:`true`)

If set to false the docs for thechildren prop will be generated even without an explicit description.

`shouldRemoveUndefinedFromOptional`: boolean

If set to true, types that are optional will not display " | undefined" in the type.

`savePropValueAsString`: boolean

If set to true, defaultValue to props will be string.Example:

Component.defaultProps={counter:123,disabled:false,};

Will return:

  counter:{defaultValue:'123',required:true,type:'number'},disabled:{defaultValue:'false',required:true,type:'boolean'}

Styled components example:

componentNameResolver:(exp,source)=>exp.getName()==="StyledComponentClass"&&getDefaultExportForFile(source);

The parser exportsgetDefaultExportForFile helper through its public API.

Example

In the example folder you can see React Styleguidist integration.

Warning: only named exports are supported. If your project uses default exports, you still need to include named exports forreact-docgen-typescript.

The componentColumn.tsx

import*asReactfrom"react";import{Component}from"react";/** * Column properties. */exportinterfaceIColumnProps{/** prop1 description */prop1?:string;/** prop2 description */  prop2:number;/**   * prop3 description   */  prop3:()=>void;/** prop4 description */  prop4:"option1"|"option2"|"option3";}/** * Form column. */exportclassColumnextendsComponent<IColumnProps,{}>{render(){return<div>Test</div>;}}

Will generate the following stylesheet:

The functional componentGrid.tsx

import*asReactfrom"react";/** * Grid properties. */exportinterfaceIGridProps{/** prop1 description */prop1?:string;/** prop2 description */  prop2:number;/**   * prop3 description   */  prop3:()=>void;/** Working grid description */  prop4:"option1"|"option2"|"option3";}/** * Form Grid. */exportconstGrid=(props:IGridProps)=>{constsmaller=()=>{return;};return<div>Grid</div>;};

Will generate the following stylesheet:

Contributions

The typescript is pretty complex and there are many different ways howto define components and their props so it's realy hard to support allthese use cases. That means only one thing, contributions are highlywelcome. Just keep in mind that each PR should also include tests forthe part it's fixing.

Thanks to all contributors without their help there wouldn't be a singlebug fixed or feature implemented. Check thecontributors tab to find outmore. All those people supported this project.THANK YOU!