or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-parser.mdcomponent-docs.mdconfiguration.mdindex.mdparser-options.mdparsing.md
tile.json

tessl/npm-react-docgen-typescript

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-docgen-typescript@2.4.x

To install, run

npx @tessl/cli install tessl/npm-react-docgen-typescript@2.4.0

index.mddocs/

React Docgen TypeScript

React Docgen TypeScript is a TypeScript-based parser for extracting React component property documentation directly from TypeScript interfaces and type definitions, eliminating the need for traditional propTypes. It integrates seamlessly with React Styleguidist and other documentation tools, offering comprehensive parsing options including prop filtering, custom component name resolution, enum value extraction, and union type handling.

Package Information

  • Package Name: react-docgen-typescript
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev react-docgen-typescript

Core Imports

import * as docgen from "react-docgen-typescript";

For CommonJS:

const docgen = require("react-docgen-typescript");

Specific imports:

import { parse, withDefaultConfig, withCustomConfig, withCompilerOptions } from "react-docgen-typescript";

Basic Usage

import * as docgen from "react-docgen-typescript";

// Parse a file with default options
const componentDocs = docgen.parse("./src/MyComponent.tsx");

// Parse with custom options
const options = {
  savePropValueAsString: true,
  shouldExtractLiteralValuesFromEnum: true,
};
const docs = docgen.parse("./src/MyComponent.tsx", options);

// Create a parser with custom configuration
const parser = docgen.withDefaultConfig(options);
const multipleDocs = parser.parse(["./src/ComponentA.tsx", "./src/ComponentB.tsx"]);

Architecture

React Docgen TypeScript is built around several key components:

  • Parser Factory Functions: High-level functions (parse, withDefaultConfig, withCustomConfig) that create configured parsers
  • Core Parser Class: The Parser class that performs the actual TypeScript AST analysis
  • Configuration System: Comprehensive options for customizing parsing behavior, filtering, and output format
  • TypeScript Integration: Deep integration with TypeScript compiler API for accurate type extraction
  • Component Detection: Smart detection of React components including functional, class, HOC, and styled components

Capabilities

Quick Parsing

Simple one-line parsing for basic use cases with sensible defaults.

function parse(
  filePathOrPaths: string | string[],
  parserOpts?: ParserOptions
): ComponentDoc[];

Quick Parsing

Parser Configuration

Create customized parsers with different TypeScript configurations and parsing options.

function withDefaultConfig(parserOpts?: ParserOptions): FileParser;
function withCustomConfig(tsconfigPath: string, parserOpts: ParserOptions): FileParser;
function withCompilerOptions(
  compilerOptions: ts.CompilerOptions,
  parserOpts?: ParserOptions
): FileParser;

interface FileParser {
  parse(filePathOrPaths: string | string[]): ComponentDoc[];
  parseWithProgramProvider(
    filePathOrPaths: string | string[],
    programProvider?: () => ts.Program
  ): ComponentDoc[];
}

Parser Configuration

Component Documentation

Complete documentation extraction including props, methods, and metadata.

interface ComponentDoc {
  expression?: ts.Symbol;
  rootExpression?: ts.Symbol;
  displayName: string;
  filePath: string;
  description: string;
  props: Props;
  methods: Method[];
  tags?: StringIndexedObject<string>;
}

interface Props extends StringIndexedObject<PropItem> {}

interface PropItem {
  name: string;
  required: boolean;
  type: PropItemType;
  description: string;
  defaultValue: any;
  parent?: ParentType;
  declarations?: ParentType[];
  tags?: {};
}

Component Documentation

Advanced Parser API

Direct access to the core Parser class for advanced use cases requiring fine-grained control.

class Parser {
  constructor(program: ts.Program, opts: ParserOptions);
  getComponentInfo(
    exp: ts.Symbol,
    source: ts.SourceFile,
    componentNameResolver?: ComponentNameResolver,
    customComponentTypes?: string[]
  ): ComponentDoc | null;
  getPropsInfo(
    propsObj: ts.Symbol,
    defaultProps?: StringIndexedObject<string>
  ): Props;
  extractPropsFromTypeIfStatelessComponent(type: ts.Type): ts.Symbol | null;
  extractPropsFromTypeIfStatefulComponent(type: ts.Type): ts.Symbol | null;
}

Advanced Parser API

Parser Options

Extensive configuration options for customizing parsing behavior, filtering, and output format.

interface ParserOptions {
  propFilter?: StaticPropFilter | PropFilter;
  componentNameResolver?: ComponentNameResolver;
  shouldExtractLiteralValuesFromEnum?: boolean;
  shouldRemoveUndefinedFromOptional?: boolean;
  shouldExtractValuesFromUnion?: boolean;
  shouldSortUnions?: boolean;
  skipChildrenPropWithoutDoc?: boolean;
  savePropValueAsString?: boolean;
  shouldIncludePropTagMap?: boolean;
  shouldIncludeExpression?: boolean;
  customComponentTypes?: string[];
}

Parser Options

Utility Functions

Default Export Helper

Generates default export names based on file names.

function getDefaultExportForFile(source: ts.SourceFile): string;

Core Types

interface PropItemType {
  name: string;
  value?: any;
  raw?: string;
}

interface Method {
  name: string;
  docblock: string;
  modifiers: string[];
  params: MethodParameter[];
  returns?: {
    description?: string | null;
    type?: string;
  } | null;
  description: string;
}

interface MethodParameter {
  name: string;
  description?: string | null;
  type: MethodParameterType;
}

interface MethodParameterType {
  name: string;
}

interface ParentType {
  name: string;
  fileName: string;
}

interface StringIndexedObject<T> {
  [key: string]: T;
}

type PropFilter = (props: PropItem, component: Component) => boolean;

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