# styleguidist/react-docgen-typescript architecture

> Architecture diagram of the GitHub repository styleguidist/react-docgen-typescript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/styleguidist/react-docgen-typescript
- Repository: https://github.com/styleguidist/react-docgen-typescript

## Overview

##### Project type and purpose
- This is an open-source Node.js library written in TypeScript (“react-docgen-typescript”).
- Its core purpose is to parse React components’ TypeScript prop definitions and emit JSON-style documentation for consumption by tools like React Styleguidist.

##### File structure
- Top level: CI/CD (.github/workflows), linting configs, README, package.json – typical npm package layout.
- /src: core modules
- index.ts – public API entrypoint exporting parse, withDefaultConfig, withCompilerOptions, withCustomConfig
- parser.ts – orchestrates reading files, invoking TypeScript compiler API, traversing AST
- propTypesParser.ts – extracts prop types and default values
- buildFilter.ts – applies user-supplied propFilter logic
- trimFileName.ts – utility for normalizing file paths
- /src/__tests__: Jest test suites covering a wide range of TS and React component scenarios.
- /examples: sample React Styleguidist integrations demonstrating usage in real projects.

##### README insights
- Exposes multiple factory functions to configure TS compiler options and docgen options.
- Optional hooks: componentNameResolver, propFilter functions, literal/union extraction toggles.
- Tight integration point: Styleguidist’s “propsParser” setting.

##### Main components & interactions
a. Components
- Client (Styleguidist or custom script)
- Public-API layer (index.ts)
- Config Loader (reads tsconfig.json or in-memory compilerOptions)
- TypeScript Compiler API (ts.Program + AST)
- Parser Pipeline
– AST Traversal & ComponentNameResolver
– PropTypesParser (extract Props interfaces, defaultProps)
– Filter Module (buildFilter applying propFilter)
– Literal/Union Extraction modules
- Output Generator (JSON structure of Component → PropItems)
- Examples & Tests (Jest runner, example projects)
- CI/CD (GitHub Actions workflows)

b. Relationships & Data Flow
- API → Config Loader: “load tsconfig or override compilerOptions”
- Config Loader → TS Compiler: “createProgram, getSourceFiles”
- TS Compiler → Parser Pipeline: “AST nodes”
- Parser Pipeline modules communicate sequentially: ComponentNameResolver → PropTypesParser → Filter → LiteralExtractors
- Pipeline → Output Generator → JSON doc data
- JSON → Client UI (Styleguidist)
- Separate flows: Examples project import library API; Tests import internal modules.

c. Architectural patterns
- Functional pipeline (chained transforms)
- Factory methods for configurability (Strategy pattern for compiler & docgen options)
- Modular separation (core ➔ utils ➔ tests ➔ examples)

d. Key technologies
- Node.js, TypeScript compiler API, Jest (tests), GitHub Actions (CI), React Styleguidist (consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client (Styleguidist or Custom Script)"]:::output

    %% Public API & Config
    PublicAPI["Public API Layer\n(withDefaultConfig, withCompilerOptions,\nwithCustomConfig)"]:::publicAPI
    ConfigLoader["Config Loader\n(load tsconfig.json or override compilerOptions)"]:::config

    %% Compiler / Parser Internals
    TSCompiler["TypeScript Compiler API\n(createProgram(), getSourceFiles)"]:::compiler
    subgraph "Parser Pipeline"
        AST["AST Traversal &\nComponentNameResolver"]:::compiler
        PropParser["PropTypesParser\n(extract Props & defaultProps)"]:::compiler
        Filter["Filter Module\n(apply propFilter)"]:::compiler
        Literal["Literal/Union Extraction"]:::compiler
        Trim["trimFileName Utility"]:::compiler
    end

    %% Output & Consumers
    OutputGen["Output Generator\n(assemble JSON docs)"]:::output
    Consumer["React Styleguidist\n(or other consumers)"]:::output

    %% Tests & Examples
    Tests["Jest Test Suites\n(src/__tests__)"]:::tests
    Examples["Example Integrations\n(examples)"]:::tests

    %% CI/CD
    CI["CI/CD Workflows\n(.github/workflows)"]:::ci

    %% Connections
    Client -->|"parse() call"| PublicAPI
    PublicAPI -->|"loadConfig()"| ConfigLoader
    ConfigLoader -->|"createProgram()"| TSCompiler
    TSCompiler -->|"AST nodes"| AST
    AST -->|"resolve names"| PropParser
    PropParser -->|"prop interfaces"| Filter
    Filter -->|"filtered props"| Literal
    Filter -->|"normalize paths"| Trim
    Literal -->|"extracted literals"| OutputGen
    PropParser -->|"initial data"| OutputGen
    OutputGen -->|"JSON docs"| Consumer

    Examples -->|"import API"| PublicAPI
    Tests -->|"test modules"| AST

    CI -->|"run tests"| Tests
    CI -->|"validate examples"| Examples

    %% Click Events
    click PublicAPI "https://github.com/styleguidist/react-docgen-typescript/blob/master/src/index.ts"
    click ConfigLoader "https://github.com/styleguidist/react-docgen-typescript/blob/master/tsconfig.json"
    click TSCompiler "https://github.com/styleguidist/react-docgen-typescript/blob/master/src/parser.ts"
    click AST "https://github.com/styleguidist/react-docgen-typescript/blob/master/src/parser.ts"
    click PropParser "https://github.com/styleguidist/react-docgen-typescript/blob/master/src/propTypesParser.ts"
    click Filter "https://github.com/styleguidist/react-docgen-typescript/blob/master/src/buildFilter.ts"
    click Trim "https://github.com/styleguidist/react-docgen-typescript/blob/master/src/trimFileName.ts"
    click OutputGen "https://github.com/styleguidist/react-docgen-typescript/blob/master/src/parser.ts"
    click Tests "https://github.com/styleguidist/react-docgen-typescript/tree/master/src/__tests__/**"
    click Examples "https://github.com/styleguidist/react-docgen-typescript/tree/master/examples/**"
    click CI "https://github.com/styleguidist/react-docgen-typescript/tree/master/.github/workflows/**"

    %% Styles
    classDef publicAPI fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef config fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef compiler fill:#d4edda,stroke:#28a745,color:#000;
    classDef output fill:#ffe5b4,stroke:#ff9933,color:#000;
    classDef tests fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef ci fill:#f3e5f5,stroke:#9c27b0,color:#000;
```
