# react/create-react-app architecture

> Architecture diagram of the GitHub repository react/create-react-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/react/create-react-app
- Repository: https://github.com/react/create-react-app

## Overview

1. This repository is a monorepo for the Create React App toolchain, not a single application. Its main output is a set of npm packages that together generate, run, test, and build React apps with minimal user configuration.

2. The top-level architecture is split into four broad areas:
   - user-facing package entrypoints and templates in `packages/`
   - shared dev/build infrastructure in `react-scripts`, `react-dev-utils`, and `react-error-overlay`
   - docs and website content in `docusaurus/`
   - release, CI, and end-to-end validation scripts in `tasks/`, `test/`, and `.github/workflows/`

3. The primary user flow starts with `create-react-app` in `packages/create-react-app`. That package is the bootstrapper invoked by `npx create-react-app ...`; it creates a new project directory, installs dependencies, and wires the generated app to `react-scripts`. The generated app is the real boundary between this repo and end-user code.

4. The generated app contract is defined by the template packages:
   - `packages/cra-template`
   - `packages/cra-template-typescript`
   These provide the scaffolded `public/` and `src/` layout, plus default app entry files, tests, and documentation. The templates are what new projects start from, while `react-scripts` supplies the behavior behind the scripts in the generated `package.json`.

5. `packages/react-scripts` is the core runtime orchestrator. It exposes the standard commands `start`, `build`, `test`, `eject`, and `init`. Internally it owns the webpack and Jest configuration, environment loading, path resolution, HTTPS/dev-server setup, and the scripts that are executed by generated apps.

6. The development-time data flow is: source files in the app go through webpack + Babel + CSS handling, then are served by webpack-dev-server. During development, errors and warnings are routed through `react-error-overlay` and related middleware so syntax/runtime problems appear in-browser. Hot reload and error formatting are handled by utilities in `react-dev-utils`.

7. The production build flow is similar but ends differently: `react-scripts build` bundles JavaScript, CSS, and static assets into hashed production artifacts, with source maps and optimizations applied. Asset imports, HTML interpolation, module scoping, and bundle reporting are all managed by the shared utilities in `react-dev-utils` and the webpack config in `react-scripts`.

8. Testing is centered on Jest under `react-scripts/config/jest`. The repo supports app-level tests, fixture-based integration tests, and environment-specific transforms for CSS, files, Babel, and TypeScript. The `test/fixtures/` tree contains many synthetic apps that verify edge cases such as asset resolution, env variable expansion, TypeScript behavior, Sass support, and webpack error formatting.

9. `packages/react-dev-utils` is the shared support layer used by `react-scripts`. It contains the reusable logic for browser launching, console clearing, file checking, source-map helpers, webpack message formatting, CSS module naming, port/process detection, and dev-server middlewares. This package is effectively the “toolbox” used by the script runner and dev server.

10. `packages/react-error-overlay` is a separate subsystem dedicated to runtime and compile-time error presentation in the browser. It includes overlay UI components, stack-frame parsing/unmapping, source-map extraction, and runtime listeners for uncaught errors and unhandled rejections. In the architecture, it sits at the boundary between the browser runtime and the developer experience.

11. Several smaller packages provide the language and compatibility contract for generated apps:
   - `packages/babel-preset-react-app` for Babel transforms
   - `packages/eslint-config-react-app` for linting rules
   - `packages/react-app-polyfill` for browser/jsdom compatibility
   - `packages/babel-plugin-named-asset-import` and `packages/confusing-browser-globals` for specific compilation/linting behaviors
   These are consumed by `react-scripts` and not typically by end users directly.

12. The repository also contains the canonical support templates embedded inside `react-scripts` itself under `packages/react-scripts/template` and `template-typescript`. These are separate from the standalone template packages, but serve the same role: defining the default starter app shape and the files that get copied into new projects.

13. The `tasks/` directory holds release and validation automation, including local registry setup, publish flows, screencast generation, and several end-to-end test scripts. This layer is mostly operational plumbing around package publishing and compatibility verification rather than product code.

14. `docusaurus/` is the documentation website subsystem. It is maintained as a separate web app with its own configuration, static assets, and pages, and is hosted via Netlify per the repo metadata. Architecturally it is independent from the CRA packages, but it documents and presents the public interface of the tooling.

15. CI and repo governance are handled through GitHub Actions workflows, issue/PR templates, and changelog files. These do not affect runtime behavior, but they matter for architecture because they enforce cross-package build/test gates across the monorepo before releases are published.

16. The key boundary to capture in a diagram is this: end-user applications depend on `react-scripts`, while `react-scripts` depends on the internal support packages and templates. Everything else in the repo exists to author, validate, document, or publish that toolchain.

Main entry points: [`packages/react-scripts`](https://github.com/react/create-react-app/tree/main/packages/react-scripts) (react-scripts), [`packages/react-scripts/config`](https://github.com/react/create-react-app/tree/main/packages/react-scripts/config) (Config core), [`packages/react-scripts/scripts`](https://github.com/react/create-react-app/tree/main/packages/react-scripts/scripts) (Commands), [`packages/create-react-app`](https://github.com/react/create-react-app/tree/main/packages/create-react-app) (create-react-app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_packages["Packages"]
  node_create_react_app["create-react-app<br/>bootstrapper"]
  node_cra_template["CRA template<br/>scaffold"]
  node_cra_template_ts["TS template<br/>scaffold"]
  node_react_scripts["react-scripts<br/>runner"]
  node_react_dev_utils["react-dev-utils<br/>support library"]
  node_error_overlay["error overlay<br/>browser overlay"]
  node_babel_preset["Babel preset<br/>compiler preset"]
  node_eslint_config["ESLint config"]
  node_polyfill["polyfill<br/>compat layer"]
  node_asset_import["asset import<br/>babel plugin"]
  node_browser_globals["globals<br/>lint rules"]
end

subgraph group_grp_docs["Docs"]
  node_website["website<br/>docs app"]
  node_docs_content["docs content<br/>documentation"]
end

subgraph group_grp_validation["Validation"]
  node_tasks["tasks<br/>automation"]
  node_fixtures["fixtures<br/>integration corpus"]
  node_gha["GitHub Actions<br/>ci workflows<br/>[workflows]"]
end

subgraph group_grp_support["Core internals"]
  node_scripts_bin["CLI entry<br/>command shim<br/>[react-scripts.js]"]
  node_scripts_config["Config core<br/>webpack/jest config"]
  node_scripts_commands["Commands<br/>build scripts"]
end

node_create_react_app -->|"scaffolds"| node_cra_template
node_create_react_app -->|"scaffolds"| node_cra_template_ts
node_create_react_app -->|"installs"| node_react_scripts
node_cra_template -->|"depends on"| node_react_scripts
node_cra_template_ts -->|"depends on"| node_react_scripts
node_react_scripts -->|"enters through"| node_scripts_bin
node_scripts_bin -->|"invokes"| node_scripts_commands
node_scripts_commands -->|"loads"| node_scripts_config
node_scripts_commands -->|"uses"| node_react_dev_utils
node_scripts_config -->|"configures"| node_babel_preset
node_scripts_config -->|"configures"| node_eslint_config
node_scripts_config -->|"targets"| node_polyfill
node_scripts_config -->|"transforms"| node_asset_import
node_scripts_config -->|"filters"| node_browser_globals
node_scripts_commands -->|"reports"| node_error_overlay
node_react_dev_utils -->|"integrates"| node_error_overlay
node_react_scripts -->|"shares"| node_react_dev_utils
node_react_scripts -->|"consumes"| node_babel_preset
node_react_scripts -->|"consumes"| node_eslint_config
node_website -->|"publishes"| node_docs_content
node_tasks -->|"executes"| node_fixtures
node_tasks -->|"publishes/tests"| node_react_scripts
node_gha -->|"drives"| node_tasks
node_gha -->|"checks"| node_react_scripts
node_gha -->|"checks"| node_website

click node_create_react_app "https://github.com/react/create-react-app/tree/main/packages/create-react-app"
click node_cra_template "https://github.com/react/create-react-app/tree/main/packages/cra-template"
click node_cra_template_ts "https://github.com/react/create-react-app/tree/main/packages/cra-template-typescript"
click node_react_scripts "https://github.com/react/create-react-app/tree/main/packages/react-scripts"
click node_scripts_bin "https://github.com/react/create-react-app/blob/main/packages/react-scripts/bin/react-scripts.js"
click node_scripts_config "https://github.com/react/create-react-app/tree/main/packages/react-scripts/config"
click node_scripts_commands "https://github.com/react/create-react-app/tree/main/packages/react-scripts/scripts"
click node_react_dev_utils "https://github.com/react/create-react-app/tree/main/packages/react-dev-utils"
click node_error_overlay "https://github.com/react/create-react-app/tree/main/packages/react-error-overlay"
click node_babel_preset "https://github.com/react/create-react-app/tree/main/packages/babel-preset-react-app"
click node_eslint_config "https://github.com/react/create-react-app/tree/main/packages/eslint-config-react-app"
click node_polyfill "https://github.com/react/create-react-app/tree/main/packages/react-app-polyfill"
click node_asset_import "https://github.com/react/create-react-app/tree/main/packages/babel-plugin-named-asset-import"
click node_browser_globals "https://github.com/react/create-react-app/tree/main/packages/confusing-browser-globals"
click node_website "https://github.com/react/create-react-app/tree/main/docusaurus/website"
click node_docs_content "https://github.com/react/create-react-app/tree/main/docusaurus/docs"
click node_tasks "https://github.com/react/create-react-app/tree/main/tasks"
click node_fixtures "https://github.com/react/create-react-app/tree/main/test/fixtures"
click node_gha "https://github.com/react/create-react-app/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_create_react_app,node_cra_template,node_cra_template_ts,node_react_scripts,node_react_dev_utils,node_error_overlay,node_babel_preset,node_eslint_config,node_polyfill,node_asset_import,node_browser_globals toneBlue
class node_website,node_docs_content toneAmber
class node_tasks,node_fixtures,node_gha toneMint
class node_scripts_bin,node_scripts_config,node_scripts_commands toneRose
```

## Components

### Packages

User-facing packages and shared runtime/tooling

- [create-react-app](https://github.com/react/create-react-app/tree/main/packages/create-react-app): bootstrapper · CLI that scaffolds a new app and installs the toolchain · `packages/create-react-app`
- [CRA template](https://github.com/react/create-react-app/tree/main/packages/cra-template): scaffold · Default JavaScript starter app files copied into new projects · `packages/cra-template`
- [TS template](https://github.com/react/create-react-app/tree/main/packages/cra-template-typescript): scaffold · TypeScript starter app files copied into new projects · `packages/cra-template-typescript`
- [react-scripts](https://github.com/react/create-react-app/tree/main/packages/react-scripts): runner · Orchestrates start, build, test, eject, and init commands · `packages/react-scripts`
- [react-dev-utils](https://github.com/react/create-react-app/tree/main/packages/react-dev-utils): support library · Reusable dev-server, webpack, browser, and formatting helpers · `packages/react-dev-utils`
- [error overlay](https://github.com/react/create-react-app/tree/main/packages/react-error-overlay): browser overlay · In-browser compile/runtime error UI and stack mapping · `packages/react-error-overlay`
- [Babel preset](https://github.com/react/create-react-app/tree/main/packages/babel-preset-react-app): compiler preset · Babel transforms for app source in development and production · `packages/babel-preset-react-app`
- [ESLint config](https://github.com/react/create-react-app/tree/main/packages/eslint-config-react-app): lint config · Linting rules used by generated apps and scripts · `packages/eslint-config-react-app`
- [polyfill](https://github.com/react/create-react-app/tree/main/packages/react-app-polyfill): compat layer · Browser and jsdom compatibility shims for generated apps · `packages/react-app-polyfill`
- [asset import](https://github.com/react/create-react-app/tree/main/packages/babel-plugin-named-asset-import): babel plugin · Named asset import transform used during compilation · `packages/babel-plugin-named-asset-import`
- [globals](https://github.com/react/create-react-app/tree/main/packages/confusing-browser-globals): lint rules · Browser global definitions used by linting · `packages/confusing-browser-globals`

### Docs

Documentation website and content

- [website](https://github.com/react/create-react-app/tree/main/docusaurus/website): docs app · Docusaurus docs site for the toolchain · `docusaurus/website`
- [docs content](https://github.com/react/create-react-app/tree/main/docusaurus/docs): documentation · End-user guides and reference pages · `docusaurus/docs`

### Validation

Release, CI, and repository-level verification

- [tasks](https://github.com/react/create-react-app/tree/main/tasks): automation · Release, publish, registry, and e2e orchestration scripts · `tasks`
- [fixtures](https://github.com/react/create-react-app/tree/main/test/fixtures): integration corpus · Synthetic apps used to validate runtime, build, and template behavior · `test/fixtures`
- [GitHub Actions](https://github.com/react/create-react-app/blob/main/.github/workflows): ci workflows · Cross-package build, lint, and test gates · `.github/workflows`

### Core internals

Shared configuration and runtime subsystems

- [CLI entry](https://github.com/react/create-react-app/blob/main/packages/react-scripts/bin/react-scripts.js): command shim · Package entrypoint that dispatches the standard commands · `packages/react-scripts/bin/react-scripts.js`
- [Config core](https://github.com/react/create-react-app/tree/main/packages/react-scripts/config): webpack/jest config · Environment, paths, webpack, dev-server, and Jest configuration · `packages/react-scripts/config`
- [Commands](https://github.com/react/create-react-app/tree/main/packages/react-scripts/scripts): build scripts · Start, build, test, eject, and init implementations · `packages/react-scripts/scripts`

## Connections

- create-react-app → CRA template: scaffolds · Chooses a starter template for new projects
- create-react-app → TS template: scaffolds · Chooses the TypeScript starter template
- create-react-app → react-scripts: installs · Creates projects configured to run via react-scripts
- CRA template → react-scripts: depends on · Generated package.json points scripts at react-scripts
- TS template → react-scripts: depends on · Generated TypeScript package.json points scripts at react-scripts
- react-scripts → CLI entry: enters through · CLI dispatch begins at the package binary
- CLI entry → Commands: invokes · Binary routes to command implementations
- Commands → Config core: loads · Commands use shared env, paths, webpack, and Jest config
- Commands → react-dev-utils: uses · Commands rely on shared dev/build helper utilities
- Config core → Babel preset: configures · Webpack and Jest pipeline use CRA Babel transforms
- Config core → ESLint config: configures · Generated apps inherit CRA lint rules
- Config core → polyfill: targets · Compatibility layer is included for older browsers and tests
- Config core → asset import: transforms · Compilation uses named asset import handling
- Config core → globals: filters · Linting excludes known browser globals from false positives
- Commands → error overlay: reports · Start/dev flow surfaces compile and runtime errors in-browser
- react-dev-utils → error overlay: integrates · Shared dev utilities connect webpack hot client and overlays
- react-scripts → react-dev-utils: shares · Core runtime uses the helper toolbox for dev-server and build UX
- react-scripts → Babel preset: consumes · App compilation depends on CRA Babel presets
- react-scripts → ESLint config: consumes · App linting depends on CRA ESLint config
- website → docs content: publishes · Docs site renders the repository documentation pages
- tasks → fixtures: executes · Automation runs synthetic app fixtures for e2e validation
- tasks → react-scripts: publishes/tests · Release and e2e scripts verify the toolchain package behavior
- GitHub Actions → tasks: drives · CI workflows run repository automation and validation scripts
- GitHub Actions → react-scripts: checks · CI gates the core package build, lint, and test paths
- GitHub Actions → website: checks · CI also validates the docs website subsystem
