Create React App — Administrator & Developer Guide

Create React App (CRA) is a Lerna monorepo providing a zero-configuration toolchain for bootstrapping and developing React applications. This guide covers the full internal architecture, every configuration surface, the build pipeline, testing infrastructure, and operational concerns for administrators, contributors, and developers who maintain or extend CRA-based projects.

For installation walkthroughs, everyday usage, and feature tutorials, see the User Guide.

Important

Create React App is officially deprecated as of the latest source. The CLI init() function displays a deprecation warning, and the Docusaurus website metadata states "Create React App is deprecated." This guide remains valuable for the thousands of production applications still running on CRA, and for understanding the architectural decisions that influenced the React ecosystem.

1. Architecture Overview

1.1 Monorepo Structure

CRA uses Lerna with npm workspaces. The top-level lerna.json declares the package locations, and package.json configures workspaces:

create-react-app/
├── packages/
│   ├── create-react-app/          # CLI scaffolder (5.1.0)
│   ├── react-scripts/             # Build toolchain (5.1.0)
│   ├── react-dev-utils/           # 33 shared utility modules (12.1.0)
│   ├── react-error-overlay/       # Browser error overlay (6.1.0)
│   ├── babel-preset-react-app/    # Babel preset (10.1.0)
│   ├── babel-plugin-named-asset-import/  # SVG named imports (0.4.0)
│   ├── eslint-config-react-app/   # ESLint configuration (7.1.0)
│   ├── confusing-browser-globals/ # Restricted globals list (1.0.11)
│   ├── react-app-polyfill/        # IE9/IE11/jsdom/stable polyfills (3.0.0)
│   ├── cra-template/              # Default JS template (1.3.0)
│   └── cra-template-typescript/   # TypeScript template (1.3.0)
├── docusaurus/
│   └── website/                   # Documentation site
└── test/                          # E2E integration tests

1.2 Package Dependency Graph

The packages form a layered dependency tree:

create-react-app (CLI)
  └── spawns npx react-scripts init

react-scripts (build toolchain)
  ├── babel-preset-react-app
  │   └── babel-plugin-named-asset-import
  ├── eslint-config-react-app
  │   └── confusing-browser-globals
  ├── react-dev-utils (33 modules)
  │   └── react-error-overlay
  └── react-app-polyfill (via templates)

cra-template / cra-template-typescript
  └── consumed by create-react-app during scaffolding

1.3 Design Principles

1. Zero configuration — react-scripts encapsulates all tooling config so end users never touch webpack, Babel, or ESLint directly.
2. Single dependency — A generated project depends only on react-scripts (plus React itself). All build tools are transitive dependencies.
3. Eject escape hatch — Running react-scripts eject copies all configuration and scripts into the project, removing the react-scripts dependency permanently.
4. Convention over configuration — Fixed directory structure (src/, public/, build/), fixed entry points (src/index.js, public/index.html), environment variable prefix (REACT_APP_*).

Note

The "single dependency" model means that upgrading react-scripts upgrades webpack, Babel, ESLint, Jest, PostCSS, and every other tool simultaneously. This is both the primary strength (simplicity) and primary pain point (version lock-in) of the architecture.

2. System Requirements

2.1 Runtime Requirements

2.2 Node.js Version Constraints

The CLI (create-react-app/index.js) enforces a minimum Node version check at startup. The engines field in react-scripts/package.json specifies the supported range.

{
  "engines": {
    "node": ">=14"
  }
}

Warning

Node.js 17+ changed the default OpenSSL provider, causing ERR_OSSL_EVP_UNSUPPORTED errors with webpack's hash functions. The workaround is setting NODE_OPTIONS=--openssl-legacy-provider before running build commands. This is a frequently reported issue (GitHub #17216).

2.3 Browser Support

Default browserslist configuration in generated projects:

{
  "browserslist": {
    "production": [">0.2%", "not dead", "not op_mini all"],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

The react-app-polyfill package provides targeted polyfills:

3. Configuration Reference

3.1 Environment Variables — Complete Reference

CRA uses environment variables as its primary configuration mechanism. Variables are loaded from .env files by config/env.js using dotenv and dotenv-expand.

.env File Loading Order

Files are loaded in this exact precedence (highest priority first):

.env.{NODE_ENV}.local    # e.g., .env.development.local
.env.local               # NOT loaded in test environment
.env.{NODE_ENV}          # e.g., .env.development
.env                     # Base defaults

All REACT_APP_* prefixed variables are injected into the client bundle via webpack's DefinePlugin as process.env.REACT_APP_*.

Build System Variables

Development Server Variables

Editor Integration Variables

CI/Test Variables

Tip

When deploying to CI, set CI=true to make the build fail on any ESLint warning. This catches issues that would be silently ignored in local development. The test runner also changes behavior: it runs all tests once and exits instead of entering watch mode.

3.2 package.json Configuration

CRA reads several fields from the project's package.json:

3.3 Advanced Proxy Configuration

For multi-target proxying, create src/setupProxy.js:

const { createProxyMiddleware } = require('http-proxy-middleware');

module.exports = function(app) {
  app.use(
    '/api',
    createProxyMiddleware({
      target: 'http://localhost:5000',
      changeOrigin: true,
    })
  );
};

This file is loaded by the dev server automatically. It receives the Express app instance and can register any middleware.

3.4 TypeScript Configuration

When tsconfig.json is present, config/modules.js reads it to configure:

• baseUrl — Creates webpack resolve.modules entry and Jest moduleDirectories
• paths — Maps to webpack resolve.alias entries and Jest moduleNameMapper

The TypeScript compiler itself runs via ForkTsCheckerWebpackPlugin in a separate process. Type errors are reported but do not block compilation unless TSC_COMPILE_ON_ERROR is false (the default).

{
  "compilerOptions": {
    "baseUrl": "src",
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx"
  }
}

Note

CRA overwrites certain tsconfig.json fields on startup. Fields like module, moduleResolution, isolatedModules, and jsx are forced to values compatible with the webpack pipeline. The rewrite is logged to the console.

3.5 Path Resolution

config/paths.js resolves all project paths from the app root. The resolved paths object:

Module file extensions searched in order:

const moduleFileExtensions = [
  'web.mjs', 'mjs', 'web.js', 'js',
  'web.ts', 'ts', 'web.tsx', 'tsx',
  'json', 'web.jsx', 'jsx',
];

4. Deployment & Scaling

4.1 Production Build Pipeline

Running react-scripts build (scripts/build.js) executes this sequence:

1. Sets NODE_ENV=production and BABEL_ENV=production
2. Loads .env files via config/env.js
3. Verifies public/index.html and src/index.js exist (checkRequiredFiles)
4. Measures existing build sizes for diff reporting (FileSizeReporter)
5. Cleans the BUILD_PATH directory
6. Copies public/ to build output (excluding index.html)
7. Runs webpack with production configuration
8. Reports gzipped file sizes with before/after comparison
9. Prints hosting instructions (printHostingInstructions)

The production webpack configuration enables:

• Code splitting — Dynamic import() creates separate chunks
• Tree shaking — Unused exports eliminated via webpack's module concatenation
• Minification — TerserPlugin (JS, targeting ECMAScript 5 output) and CssMinimizerPlugin (CSS)
• Asset hashing — Content hashes in filenames for cache busting ([name].[contenthash:8].js)
• Chunk optimization — splitChunks.chunks: 'all' with runtimeChunk: true
• Source maps — Generated unless GENERATE_SOURCEMAP=false

4.2 Build Output Structure

build/
├── static/
│   ├── js/
│   │   ├── main.[hash].js          # Application code
│   │   ├── main.[hash].js.map      # Source map
│   │   ├── [id].[hash].chunk.js    # Split chunks
│   │   └── runtime-main.[hash].js  # Webpack runtime (or inlined)
│   ├── css/
│   │   ├── main.[hash].css         # Extracted CSS
│   │   └── main.[hash].css.map     # CSS source map
│   └── media/
│       └── [name].[hash].[ext]     # Images, fonts, other assets
├── index.html                       # Processed HTML with injected assets
├── asset-manifest.json              # Map of logical names to hashed paths
├── manifest.json                    # PWA web app manifest (from public/)
└── service-worker.js                # Generated by WorkboxWebpackPlugin (if src/service-worker.js exists)

4.3 Deployment Targets

The printHostingInstructions.js utility detects the deployment target from package.json and prints context-specific instructions.

Static File Server

npm install -g serve
serve -s build

The -s flag enables single-page app mode (rewrites all routes to index.html).

Subpath Deployment

Set homepage in package.json to configure the base URL:

{
  "homepage": "https://example.com/my-app"
}

This sets PUBLIC_URL to /my-app, ensuring all asset paths are correctly prefixed. The %PUBLIC_URL% placeholder in public/index.html is replaced at build time by InterpolateHtmlPlugin.

CDN / Custom Build Directory

BUILD_PATH=dist react-scripts build

Tip

For GitHub Pages deployment, set "homepage": "https://username.github.io/repo-name". For relative paths (useful when the deployment path is unknown at build time), set "homepage": "." — this makes all asset references relative.

4.4 Service Worker (PWA)

CRA supports Progressive Web App features via Workbox. When src/service-worker.js (or .ts) exists, WorkboxWebpackPlugin.InjectManifest processes it:

• Injects a precache manifest of all build assets
• The service worker controls caching strategy
• The default template from cra-template registers the service worker only in production

In development, noopServiceWorkerMiddleware serves a no-op service worker that clears any previously registered cache, preventing stale content.

5. Operations

5.1 The Four Commands

react-scripts start (scripts/start.js)

1. Sets NODE_ENV=development
2. Verifies required files exist
3. Detects available port (default 3000, auto-increments via detect-port-alt)
4. Creates webpack compiler with development config
5. Starts webpack-dev-server with HMR and error overlay
6. Opens browser (unless BROWSER=none)

Key dev server features:

• Hot Module Replacement via webpackHotDevClient.js (not webpack's default client)
• React Fast Refresh for state-preserving component updates (unless FAST_REFRESH=false)
• Error overlay (react-error-overlay) for runtime and compilation errors
• Proxy support (single-origin via package.json or multi-target via src/setupProxy.js)
• History API fallback for SPA routing
• Static file serving from public/

react-scripts build (scripts/build.js)

Described in Section 4.1 above. Exits with code 1 on failure (or when CI=true and warnings exist).

react-scripts test (scripts/test.js)

1. Sets NODE_ENV=test
2. Loads .env files (skips .env.local)
3. Configures Jest with config/jest/ transforms
4. Runs in watch mode by default (unless CI=true or --watchAll=false)

See Section 8.4 for full testing details.

react-scripts eject (scripts/eject.js)

Eject is a one-way operation that copies all encapsulated configuration into the project:

1. Confirms via interactive prompt (unless --force)
2. Copies config/ directory (webpack, Babel, Jest, env, paths, etc.)
3. Copies scripts/ directory (start, build, test)
4. Updates package.json:
   • Moves all react-scripts dependencies to the project
   • Replaces script commands with direct node scripts/*.js calls
   • Removes react-scripts dependency
   • Adds jest, babel, and eslintConfig sections
5. Stages all changes in git (if repository detected)

Caution

Ejecting is irreversible. Once ejected, the project assumes ownership of all configuration files. Future react-scripts updates (bug fixes, security patches, dependency upgrades) will not apply. Before ejecting, consider alternatives: CRACO, react-app-rewired, or customize-cra for non-destructive config overrides.

5.2 Preflight Checks

Before running any command, react-scripts performs a verifyPackageTree() check that detects mismatched versions of critical dependencies (Babel, webpack, Jest, ESLint). This catches scenarios where a parent project or global install provides a conflicting version.

Set SKIP_PREFLIGHT_CHECK=true to bypass this (not recommended for production).

5.3 Webpack Cache Management

CRA uses webpack 5's persistent filesystem cache stored in node_modules/.cache/:

cache: {
  type: 'filesystem',
  version: environmentHash,  // Hash of NODE_ENV + all env vars
  cacheDirectory: paths.appWebpackCache,
  store: 'pack',
  buildDependencies: {
    defaultWebpack: ['webpack/lib/'],
    config: [__filename],
    tsconfig: [paths.appTsConfig, paths.appJsConfig].filter(f => fs.existsSync(f)),
  },
}

The cache is automatically invalidated when:

• Any environment variable changes (via environmentHash)
• webpack config file changes
• tsconfig.json or jsconfig.json changes

To manually clear the cache:

rm -rf node_modules/.cache

5.4 Error Handling

The error overlay (react-error-overlay) injects an iframe into the page to display:

• Compilation errors (webpack build failures)
• Runtime errors (uncaught exceptions, unhandled promise rejections)
• Source-mapped stack traces with click-to-open-in-editor

The overlay hooks into window.onerror and window.onunhandledrejection. In production builds, the overlay is not included.

Warning

The dev server's DANGEROUSLY_DISABLE_HOST_CHECK flag disables DNS rebinding protection. Only use this in trusted network environments. If you need to access the dev server from other devices, prefer --host 0.0.0.0 with the default host check enabled.

6. Performance

6.1 Webpack Production Optimizations

6.2 Development Performance

6.3 Build Size Analysis

CRA includes FileSizeReporter which reports gzipped sizes after each build:

File sizes after gzip:

  48.12 KB  build/static/js/main.a1b2c3d4.js
  1.42 KB   build/static/css/main.e5f6a7b8.css

For deeper analysis, the asset-manifest.json maps logical names to physical files with hashes, enabling automated size tracking.

6.4 CSS Performance

• CSS Modules: .module.css and .module.scss files get locally scoped class names via css-loader modules mode, using the ident pattern [path][name]__[local]--[hash:base64:5] (generated by getCSSModuleLocalIdent)
• PostCSS Autoprefixer: Automatically adds vendor prefixes based on browserslist
• Tailwind CSS: Auto-detected when tailwind.config.js exists in project root; PostCSS config includes tailwindcss plugin
• MiniCssExtractPlugin: Production CSS is extracted to separate files (development uses style-loader for HMR)

Note

Sass support requires installing sass (Dart Sass). The webpack config conditionally enables sass-loader for .scss and .sass files, including CSS Module variants (.module.scss, .module.sass). No configuration is needed beyond the install.

7. Security

7.1 Environment Variable Isolation

Only variables prefixed with REACT_APP_ are embedded in the client bundle. This is enforced in config/env.js:

const REACT_APP = /^REACT_APP_/i;

function getClientEnvironment(publicUrl) {
  const raw = Object.keys(process.env)
    .filter(key => REACT_APP.test(key))
    .reduce((env, key) => {
      env[key] = process.env[key];
      return env;
    }, {
      NODE_ENV: process.env.NODE_ENV || 'development',
      PUBLIC_URL: publicUrl,
      WDS_SOCKET_HOST: process.env.WDS_SOCKET_HOST,
      WDS_SOCKET_PATH: process.env.WDS_SOCKET_PATH,
      WDS_SOCKET_PORT: process.env.WDS_SOCKET_PORT,
      FAST_REFRESH: process.env.FAST_REFRESH !== 'false',
    });
  // ...
}

Caution

Any REACT_APP_* variable is embedded directly into the JavaScript bundle and visible to anyone who inspects the built files. Never store secrets, API keys with write access, database credentials, or other sensitive values in REACT_APP_* variables. These are for public configuration only (e.g., API base URLs, feature flags, analytics IDs).

7.2 Module Scope Enforcement

ModuleScopePlugin restricts imports to files within src/ and node_modules/. This prevents:

• Accidentally importing build artifacts
• Importing files outside the source tree that webpack might not process correctly
• Breaking the build when files are in unexpected locations

Allowed exceptions: package.json (for reading homepage, proxy, etc.) and files in node_modules/.

7.3 Import Restriction — Confusing Browser Globals

confusing-browser-globals exports a list of 56 browser global variables (event, name, status, length, origin, open, close, etc.) that are restricted by the ESLint config. This prevents accidental use of global variables that shadow common local variable names:

// ESLint error: Unexpected use of 'event'
function handleClick() {
  console.log(event); // Meant to use the parameter, accidentally got window.event
}

7.4 Host Check Protection

The webpack dev server validates the Host header to prevent DNS rebinding attacks. The webpackDevServer.config.js allows:

• localhost and loopback addresses
• The configured HOST environment variable
• Any host when DANGEROUSLY_DISABLE_HOST_CHECK=true (insecure)

7.5 HTTPS Configuration

For local HTTPS development:

HTTPS=true react-scripts start

For custom certificates (e.g., for testing with real domain names):

SSL_CRT_FILE=./cert.pem SSL_KEY_FILE=./key.pem HTTPS=true react-scripts start

The getHttpsConfig.js module reads and validates the certificate and key files, providing clear error messages if they are missing or unreadable.

7.6 Source Map Security

Production source maps are generated by default, exposing the original source code. For production deployments where source exposure is a concern:

GENERATE_SOURCEMAP=false react-scripts build

Alternatively, upload source maps to an error tracking service (Sentry, Bugsnag) and exclude .map files from the production server.

Important

The asset-manifest.json file lists all build outputs including source maps. If you serve this file publicly, automated tools can discover and download your source maps even if they are not linked in the JavaScript files.

8. Developer Internals

8.1 Webpack Configuration Deep Dive

config/webpack.config.js exports a function that takes webpackEnv ('development' or 'production') and returns the full webpack config. Key structural decisions:

Entry Points

entry: [
  // Development: WebSocket client for HMR
  isEnvDevelopment && require.resolve('react-dev-utils/webpackHotDevClient'),
  // Application entry
  paths.appIndexJs,
].filter(Boolean)

Output Configuration

output: {
  path: paths.appBuild,
  pathinfo: isEnvDevelopment,        // Module path comments in dev
  filename: isEnvProduction
    ? 'static/js/[name].[contenthash:8].js'
    : 'static/js/bundle.js',
  chunkFilename: isEnvProduction
    ? 'static/js/[name].[contenthash:8].chunk.js'
    : 'static/js/[name].chunk.js',
  assetModuleFilename: 'static/media/[name].[hash][ext]',
  publicPath: paths.publicUrlOrPath,
}

Loader Pipeline (in order of rule matching)

Complete Plugin List

8.2 Babel Configuration

babel-preset-react-app configures Babel with these presets and plugins:

Presets

Plugins

8.3 ESLint Configuration

eslint-config-react-app extends/uses these plugins:

ESLint runs as a webpack plugin (ESLintPlugin) during compilation, reporting errors in the terminal and error overlay. The eslintFormatter.js utility formats output with file paths and line numbers.

8.4 Testing Infrastructure

Jest Configuration

CRA configures Jest 27 with the following from scripts/test.js and the createJestConfig function:

{
  roots: ['<rootDir>/src'],
  collectCoverageFrom: ['src/**/*.{js,jsx,ts,tsx}', '!src/**/*.d.ts'],
  setupFiles: ['react-app-polyfill/jsdom'],
  setupFilesAfterFramework: [paths.testsSetup],  // src/setupTests.{js,ts}
  testMatch: [
    '<rootDir>/src/**/__tests__/**/*.{js,jsx,ts,tsx}',
    '<rootDir>/src/**/*.{spec,test}.{js,jsx,ts,tsx}',
  ],
  testEnvironment: 'jsdom',
  transform: {
    '^.+\\.(js|jsx|mjs|cjs|ts|tsx)$': 'config/jest/babelTransform.js',
    '^.+\\.css$': 'config/jest/cssTransform.js',
    '^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)': 'config/jest/fileTransform.js',
  },
  moduleNameMapper: { '^.+\\.module\\.(css|sass|scss)$': 'identity-obj-proxy' },
  watchPlugins: [
    'jest-watch-typeahead/filename',
    'jest-watch-typeahead/testname',
  ],
}

Custom Transforms

Watch Mode

In non-CI environments, Jest runs in --watch mode by default (if git/hg is detected) or --watchAll otherwise. The jest-watch-typeahead plugins add interactive filtering by filename and test name.

Tip

The src/setupTests.js (or .ts) file runs before every test file. Use it to configure testing-library matchers, mock global APIs, or set up test fixtures. The default template includes @testing-library/jest-dom for DOM assertion matchers like toBeInTheDocument() and toHaveTextContent().

8.5 react-dev-utils Module Reference

All 33 utility modules in packages/react-dev-utils/ (91 KB total):

8.6 react-error-overlay Internals

The error overlay is a standalone package that renders compilation and runtime errors in an iframe injected into the page:

• iframe isolation — Styles and scripts do not conflict with the application
• Source mapping — Uses source-map library to map transpiled stack traces back to original source
• Click-to-source — Clicking a stack frame calls the dev server's launch-editor endpoint
• Runtime hooks — Listens to window.onerror and window.onunhandledrejection
• API — startReportingRuntimeErrors({onError, filename}), stopReportingRuntimeErrors(), setEditorHandler(handler), dismissBuildError(), reportBuildError(error)

The overlay is included only in development builds. It is imported by webpackHotDevClient.js.

8.7 create-react-app CLI Internals

The CLI package (packages/create-react-app/) handles project scaffolding:

CLI Arguments

Scaffolding Process

1. Validates project name (validate-npm-package-name)
2. Creates project directory
3. Writes initial package.json
4. Detects package manager (npm, yarn, or pnpm)
5. Installs react, react-dom, and react-scripts (or specified --scripts-version)
6. Downloads and extracts template package
7. Runs react-scripts init which:
   • Copies template files into the project
   • Sets up package.json scripts (start, build, test, eject)
   • Initializes git repository
   • Displays success message with next steps

8.8 Package Manager Detection

The CLI and react-scripts detect the active package manager through multiple signals:

This affects install commands, lockfile handling, and post-build instructions.

9. Integration Points

9.1 Customization Without Ejecting

Several community tools allow overriding CRA's webpack config without ejecting:

These tools work by intercepting the config before it reaches webpack and applying user-defined modifications.

9.2 Template System

Custom templates are npm packages named cra-template-*. Template structure:

cra-template-{name}/
├── template/           # Files copied into the new project
│   ├── public/
│   ├── src/
│   └── gitignore       # Renamed to .gitignore
├── template.json       # Additional dependencies and scripts
└── package.json        # Template package metadata

template.json supports:

{
  "dependencies": {
    "additional-package": "^1.0.0"
  },
  "scripts": {
    "custom-script": "echo hello"
  }
}

9.3 Monorepo Compatibility

CRA projects can live inside monorepos with caveats:

• ModuleScopePlugin restricts imports to src/ — shared packages must be in node_modules (hoisted) or the plugin must be disabled (via eject or CRACO)
• babel-loader only processes files inside appSrc — shared source outside src/ will not be transpiled
• Webpack's resolve.modules includes only the project's node_modules, not parent directories (hoisting handles this for most package managers)

9.4 CI/CD Integration

For memory-constrained CI environments:

NODE_OPTIONS=--max-old-space-size=4096 react-scripts build

Note

When CI=true, the build process treats all ESLint warnings as errors and fails the build. The test runner also runs all tests once and exits (no watch mode). This is the recommended configuration for all CI pipelines.

9.5 Known Issues and Workarounds

9.6 Dependency Version Matrix

Core dependency versions locked by react-scripts 5.1.0:

Warning

Installing different versions of these dependencies alongside react-scripts triggers the preflight version check and may cause unpredictable behavior. If the preflight check blocks startup, investigate the version conflict rather than setting SKIP_PREFLIGHT_CHECK=true.

9.7 Migration Paths

Since CRA is deprecated, the recommended migration targets are:

For Vite migration, the key changes are:

• Replace react-scripts scripts with vite / vite build / vitest
• Convert REACT_APP_* env vars to VITE_*
• Move public/index.html to project root and add <script type="module" src="/src/index.jsx"> tag
• Replace %PUBLIC_URL% with Vite's asset handling
• Update jest.config to vitest.config if using Vitest