Introduction

react-diagram-schema is a CLI tool that statically parses React source code to generate a structured JSON schema representing a component tree rooted at a chosen entry component.

No installation or configuration required to get started.
You can generate a schema starting from any component, from a single isolated component to the full application tree.

The schema is intended to be consumed by tooling and integrations (like the visualizer below, or tools you build yourself).

Quick Start

npx react-diagram-schema ./src/App.jsx

Downstream Consumer Example:

npx react-diagram-visualizer ./src/App.jsx

react-diagram-visualizer is a web application that internally generates and consumes the JSON schema to render an interactive UML-style diagram.

Table of Contents

• Installation
• Usage
• Example Output
• Arguments
• Flags
• Troubleshooting
• About JSON Schema
• Dependencies
• Limitations
• Roadmap
• Contributing
• License

Installation

To Install Locally:

npm install react-diagram-schema

To Install Globally:

npm install -g react-diagram-schema

Usage

Run directly with npx (no installation required)

npx react-diagram-schema <entryDirectory|entryFile> [rootComponentName]

Examples:

npx react-diagram-schema ./src/App.jsx

npx react-diagram-schema ./src/components/App/ App

Run after local or global installation:

react-diagram-schema <entryDirectory|entryFile> [rootComponentName]

Example Output

The current working directory is ./react-diagram-schema/

Command

• Targeting the sample file App.js (located in ./sample-components/) for component App:

  npx react-diagram-schema ./sample-components/ App

Result
I get the following messages in the Console:

✅ Success: Parsed 4 components from 2 files in 50.585535 milliseconds

💾 Saved: Schema has been written to react-diagram-schema/schema.json

The schema.json file is written to your current working directory, and has the following structure:

{
  "App::sample-components/App.js": {
    "name": "App",
    "description": "",
    "descendants": [
      "Header::sample-components/Header.js",
      "Content::sample-components/App.js"
    ],
    "internal": {
      "states": [
        ["count", "setCount"],
        ["theme", "setTheme"]
      ],
      "functions": ["buttonHandler", "B"]
    },
    "external": {
      "props": ["children", "propA", "propB", "propC"],
      "context": [
        {
          "source": "FavouriteColorContext",
          "values": ["favouriteColor"]
        },
        {
          "source": "FavouriteThemeContext",
          "values": ["theme1", "theme2"]
        }
      ],
      "constants": []
    },
    "defaultExport": false,
    "location": {
      "line": 7,
      "filepath": "sample-components/App.js"
    },
    "isEntryComponent": true
  },
  "Content::sample-components/App.js": {
    "name": "Content",
    "description": "",
    "descendants": [],
    "internal": {
      "states": [],
      "functions": []
    },
    "external": {
      "props": [],
      "context": [],
      "constants": []
    },
    "defaultExport": false,
    "location": {
      "line": 43,
      "filepath": "sample-components/App.js"
    }
  },
  "B::sample-components/App.js": {
    "name": "B",
    "description": "",
    "descendants": [],
    "internal": {
      "states": [],
      "functions": ["C"]
    },
    "external": {
      "props": ["color"],
      "context": [],
      "constants": []
    },
    "defaultExport": false,
    "location": {
      "line": 17,
      "filepath": "sample-components/App.js"
    },
    "nested": true
  },
  "Header::sample-components/Header.js": {
    "name": "Header",
    "description": "",
    "descendants": [],
    "internal": {
      "states": [],
      "functions": []
    },
    "external": {
      "props": [],
      "context": [],
      "constants": []
    },
    "defaultExport": false,
    "location": {
      "line": 3,
      "filepath": "sample-components/Header.js"
    }
  }
}

This schema can then be rendered as an interactive diagram using react-diagram-visualizer:

Checkout react-diagram-visualizer to learn more about the visualizer.

Another option is to pass the schema to your own custom built tools for further analysis.

Arguments

The CLI tool accepts two positional arguments:

1. (required) <entryDirectory> or <entryFile>
   This is a path to your application's entry directory or entry file.
   Example: ./src/ or ./src/index.js

2. (optional) [rootComponentName]
   This is the name of the React component defined in the entry file.
   If omitted, the tool falls back to the default export,
   either from the entry file (if <entryFile> was provided)
   or an index file (index.tsx, index.ts, index.jsx, or index.js) in the entry directory.
   Example: App or Button

Examples:

1. If the name of the component matches the name of the file,
   supplying just the <entryFile> or the <entryDirectory> + [rootComponentName] is sufficient:

• For an App.jsx file, targeting a component App,

  npx react-diagram-schema ./src/components/App.jsx

  npx react-diagram-schema ./src/components/App/ App

2. index.(js/jsx/ts/tsx) files are checked automatically.
   Thus, when targeting an index file, <entryFile> becomes optional:

• For an index.jsx file, targeting a component Scroll

  npx react-diagram-schema ./src/components/ Scroll

  npx react-diagram-schema ./src/components/index.jsx Scroll

3. If the name of the component does not match the name of the file,
   you must explicitly supply both <entryFile> + [rootComponentName]:

• targeting a component Button

  npx react-diagram-schema ./src/components/App/App.jsx Button

4. If the target component is not supplied, the fallback is
   either assuming that the component name matches the file name (i.e. the first example)
   or assuming that the target component is default exported:

• targeting a default exported component

  npx react-diagram-schema ./src/components/index.jsx

Flags

Output File Purpose: specify the filename/path where the schema should be saved.
Note: By default, a schema.json file will be saved in your current working directory Usage: append --out or --output to the end of your command like so:

react-diagram-schema ./src App --out ./archive/my-schema.json

Quiet
Purpose: suppresses success, error, and warning console messages. Critical errors will still be printed if the program fails to run. A request to overwrite a pre-existing json file will also be printed if relevant.
Usage: append --quiet to the end of your command like so:

react-diagram-schema ./components/App App --quiet

Verbose
Purpose: prints all error and warning console messages.
Usage: append --verbose to the end of your command like so:

react-diagram-schema ./components/App App --verbose

Debug
Purpose: prints error and warning console messages, and also prints the generated JSON schema to the console for quick inspection.
Usage: append --debug to the end of your command like so:

react-diagram-schema ./components/App App --debug

Troubleshooting

:heavy_exclamation_mark: Empty Schema

Message

✅ Success: Parsed 0 components from 0 files in 0.252575 milliseconds

This runtime error implies that the CLI tool could not find any components in the provided/fallback files.

Tips:

• Check whether the supplied <entryFile> contains at least one component declaration.
• If supplying an <entryDirectory>, check whether a [rootComponentName].(js/jsx/ts/tsx) or index.(js/jsx/ts/tsx) file exists in the entry directory.

:x: Error
invalid path

Message

Error: (build-schema) invalid path "undefined", please provide a valid directory or file path as your first argument (e.g. "./src")

This error may occur in the following scenarios:

1. The first argument to react-diagram-schema was omitted.
2. An invalid first argument was provided (for example, the file path or directory does not exist).

Hint:
Ensure the current directory and first argument are valid before running react-diagram-schema (example argument: ./components)

:x: Error
invalid component name

Message

Error: (build-schema) invalid component name "app", please provide a valid component name as your second argument (e.g. "App")

This error may occur in the following scenarios:

1. An invalid second argument was provided (e.g. the component name did not start with a capital letter).

Hint:
Ensure the second argument matches the name of the component defined in the entry file (e.g. ComponentName defined in ComponentName.js or in index.js)

:warning: Warning
descendant could not be resolved

Message

WARNING: (build-schema) the descendant <descendant-name> of component <component-name> could not be resolved within the file <file-path>

This warning may occur in the following scenarios:

1. The file indicated in <file-path> does not exist or could not be found by the parser.

Hint:
Look for the file indicated in <file-path>

About JSON Schema

The schema is a static architectural model, serialized as JSON, intended for downstream tools.

The schema includes all components discovered during traversal from the chosen entry point, including components that are not directly rendered.

• The schema stores parsed components as objects, parses each component's:
  • name
  • description (the component's purpose, which will be integrated post-MVP using inline comments)
  • descendants (the component's direct children)
  • location (more specifically, the file path and declaration line)

• The schema stores the parsed components' internally defined data such as:
  • states and state setters
  • function declarations

• The schema stores the parsed components' externally defined data such as:
  • props
  • context dependencies
  • constants (which will be integrated in future releases)

• other details:
  • nested: true indicates a component declared inside another component’s scope.
  • For default-exported components without an explicit name, the schema assigns a name derived from the file name.

The schema

• describes your app’s structure
• integrates seamlessly with react-diagram-visualizer (a ReactFlow based tool that renders the schema as an interactive UML-style diagram)
• can power your custom built tools or workflows (feel free to reuse it however you like)

What you can build with the schema:

The schema enables custom tooling for various development workflows

• Visualization tools - Render component hierarchies, data flow, and relationships (e.g., react-diagram-visualizer)
• Architectural analysis - Verify correctness, detect anti-patterns, measure complexity
• Documentation generators - Auto-generate architecture docs synced with code
• Refactoring assistants - Prototype structural changes and assess impact
• Onboarding tools - Help new developers navigate unfamiliar codebases

Dependencies

• @babel/parser - Parses JavaScript code into an AST
• @babel/traverse - Walks the AST and extracts component data
• typescript - Compiles TypeScript/TSX files into JavaScript/JSX

Limitations

This CLI tool currently parses JavaScript (.js / .jsx) and TypeScript (.ts / .tsx) files but does not extract additional information from TypeScript files.

Extracting types from .ts / .tsx files is a planned feature that could be introduced in the future. To learn more regarding next steps and future plans, check out the ROADMAP.md document.

Roadmap

Please visit ROADMAP.md to view the project's progress, and planned features.

Contributing

For local development or contributing, see CONTRIBUTING.md.

License

MIT