CodeVetter · Repo Unpack evidence
react/create-react-app
github.com/react/create-react-app ↗ · 505 files · 1.4 MB
Create React App [!CAUTION] ## Deprecated Create React App was one of the key tools for getting a React project up-and-running in 2017-2021, it is now in long-term stasis and we recommend that you migrate to one of React frameworks documented on Start a New Re
Overview
Create React App is a monorepo that scaffolds opinionated React applications and ships the build, lint, test, and dev-server toolchain those apps use. The CLI (`create-react-app`) copies a template, installs dependencies, and the generated app is then driven by `react-scripts` (webpack, Babel, Jest, ESLint). This brief is grounded in the repo at commit 6254386531d263688ccfa542d0e628fbc0de0b28.
System map
The published surface is a Lerna/Yarn workspaces monorepo under packages/. Users invoke the create-react-app binary, which delegates project creation to react-scripts/scripts/init.js and then leaves the app running on react-scripts start/build/test. Runtime boundaries are Node for the CLI and scripts, webpack-dev-server for development, Jest for tests, and static file output for production. Docs live in docusaurus/website and deploy via Netlify. CI is GitHub Actions (build-and-test, lint, e2e).
- Root package.json names the monorepo create-react-app, marks it private, requires Node >=14, and uses Yarn workspaces for packages/*. Scripts include create-react-app (node tasks/cra.js), build (node tasks/build.js), test (tasks/e2e-simple.sh), e2e (tasks/e2e-simple.sh + tasks/e2e-behavior.sh), e2e:docker (tasks/e2e-docker.sh), eslint, format, and prettier.
- lerna.json pins Lerna 3.22.1 with version 5.1.0, npmClient yarn, and useWorkspaces true, so package publishes are version-locked together rather than independently versioned at publish time.
- The user-facing CLI entry is packages/create-react-app/index.js. It checks Node >=14 via semver, validates the project directory with createApp, then spawns react-scripts/scripts/init.js through executeNodeScript, passing root, appName, verbose, originalDirectory, and template.
- create-react-app's bin is create-react-app -> index.js and its only runtime dependency is react-scripts. CLI flags include --scripts-version, --template, --use-pnp, --verbose, and --info (which delegates to envinfo).
- react-scripts is the toolchain package (bin react-scripts -> bin/react-scripts.js). Its dependencies include webpack 5, webpack-dev-server 4, babel-loader, @babel/core, Jest 27, eslint 8, css-minimizer-webpack-plugin, postcss-loader, sass-loader, workbox-webpack-plugin, and html-webpack-plugin.
- react-scripts bin switches on process.argv[2]: start, build, and test require the matching scripts/* module; eject runs scripts/eject. Unknown commands print a hint that CRA commands are start, build, test, and eject.
- Webpack configs are three modules under packages/react-scripts/config: webpack.config.js (shared factory), webpackDevServer.config.js, and an env loader (env.js) plus paths.js and modules.js. babel-preset-react-app and eslint-config-react-app are sibling packages consumed by those configs.
- Docs site package cra-docs (docusaurus/website) is a Docusaurus 2 app. Scripts are start (docusaurus start), build, deploy, and swizzle. netlify.toml publishes docusaurus/website/build with NODE_VERSION 16.8.0 and a docs redirect from / to /docs/getting-started.
- CI workflow build-and-test.yml runs on push to main and on pull_request. Jobs include a build job and an e2e-docker job that calls the reusable workflow e2e-base.yml. lint.yml runs separately.
- The default app template is packages/cra-template (template.json + template/public and template/src). TypeScript variant is packages/cra-template-typescript. Templates declare package.json dependencies (react, react-dom, react-scripts, web-vitals, testing-library) and scripts start/build/test/eject.
- react-dev-utils is the shared Node library for the CLI and scripts: WebpackDevServerUtils, createCompiler, FileSizeReporter, InterpolateHtmlPlugin, ModuleScopePlugin, eslintFormatter, and browsersHelper. react-error-overlay is a separate iframe overlay package built with its own webpack config.
- There is no application database. Persistence is the generated project directory on disk (files copied from the template, package.json written by init, yarn.lock or package-lock from the installer) plus webpack's in-memory dev middleware and the build/ output folder.
Feature catalog
User-facing features split into the scaffolder CLI, the four react-scripts commands, the default JS and TS templates, and the documentation site. The generated app is a single-page React demo (logo, edit-src hint, learn-react link) with Jest/Testing Library already wired and a production build that fingerprints assets. Optional capabilities include CSS/Sass/CSS Modules, SVG ReactComponent imports, TypeScript, Jest watch mode, HTTPS dev server, proxy, PUBLIC_URL, and eject.
- CLI create-react-app <project-directory> accepts --verbose, --info, --scripts-version <version>, --template <name>, and --use-pnp. --info prints environment diagnostics via envinfo and exits. Template names are normalized: cra-template prefix is added unless the name contains a scope or file: prefix.
- init.js is the post-install initializer. It copies the template (excluding template.json), merges template.json into package.json (dependencies, scripts, eslintConfig, browserslist), renames gitignore to .gitignore, tries git init and an initial commit, and prints the success message with cd/npm start instructions.
- react-scripts start loads env, chooses a port (default 3000 via choosePort), creates a webpack compiler from configFactory('development'), starts WebpackDevServer, opens the browser unless --no-open or BROWSER=none, and installs SIGINT/SIGTERM handlers that close the server.
- react-scripts build empties paths.appBuild, runs the production webpack compiler, prints gzip file sizes via FileSizeReporter, copies public/ (minus index.html) into build/, and warns when the build is not deployed to the root because PUBLIC_URL or homepage is set.
- react-scripts test is a thin wrapper around Jest. It sets BABEL_ENV and NODE_ENV to test, injects a watch mode (unless CI or --watchAll/--watchAll=false), and forwards argv to jest.run. Config comes from packages/react-scripts/scripts/utils/createJestConfig.js.
- react-scripts eject copies webpack, Babel, and ESLint config into the app, removes the react-scripts dependency, and is irreversible. The eject script checks the git status is clean unless --force or --no-git is passed, then rewrites package.json scripts from react-scripts <cmd> to node scripts/<cmd>.js.
- The default JS template App renders a header with img logo (logo.svg), a paragraph telling the user to edit src/App.js, and an anchor to https://reactjs.org. App.css, index.js (ReactDOM.createRoot or ReactDOM.render depending on template version), and public/index.html with %PUBLIC_URL% placeholders ship alongside it.
- cra-template-typescript ships App.tsx, react-app-env.d.ts, and tsconfig.json. Its template.json adds typescript, @types/node, @types/react, @types/react-dom, and @types/jest. The typecheck fixture App.tsx exists to assert tsc behavior in integration tests.
- Dev server features in webpackDevServer.config.js include hot reloading, historyApiFallback, gzip, public/ static directory, optional proxy from package.json proxy, HTTPS when HTTPS=true, and allowedHosts driven by HOST / DANGEROUSLY_DISABLE_HOST_CHECK. SockJS and webpack-dev-server client overlay integrate with react-error-overlay.
- Asset pipeline: file-loader/asset modules for images and fonts; babel-plugin-named-asset-import turns SVG imports named ReactComponent into SVGR components; CSS and CSS Modules via css-loader; Sass via sass-loader when the user installs sass. PostCSS applies autoprefixer using browserslist.
- eslint-config-react-app enables eslint:recommended, plugin:react/recommended, react-hooks, jsx-a11y, and (when the typescript parser is present) @typescript-eslint. jest and testing-library plugins are turned on only when those packages resolve from the app. confusing-browser-globals supplies restricted globals (event, name, length, etc.).
- PWA support is conditional: webpack.config.js adds Workbox InjectManifest or GenerateSW only when src/service-worker.js (or serviceWorker.ts) exists. The modern templates do not include a service worker by default; older template copies may still reference serviceWorkerRegistration.
Data flow
Two data planes exist. Scaffolding: argv and template package contents flow through createApp into a new directory, then init.js materializes package.json, source files, and git state. App runtime: source files, env files, and public/ flow through webpack (Babel, CSS, asset plugins) into either an in-memory dev server or a build/ directory. Jest is a third consumer of the same Babel pipeline via babel-jest and a derived config. Environment variables are the main cross-cutting input: only NODE_ENV, PUBLIC_URL, and REACT_APP_* are inlined into the client bundle.
- CLI argv is parsed in createReactApp.js with a manual loop (not commander). project directory is resolved with path.resolve. If the directory exists and is not empty (except .git, .hg, LICENSE, README, and a few known files), createApp refuses to continue unless the name is . for the current directory.
- Template resolution: getTemplateInstallPackage turns --template typescript into cra-template-typescript, keeps scoped names, and supports file: paths and version suffixes (typescript@next). The template package and react-scripts are installed into the new app before init.js runs.
- init.js reads template/template.json via fs, copies the template directory with fs-extra, deletes the template's package.json and README if present so the generated package.json wins, then Object.assign-merges dependencies, scripts, eslintConfig, browserslist, babel, and jest keys.
- paths.js resolves appPath from process.cwd(), then appSrc (src/), appPublic (public/), appHtml (public/index.html), appIndexJs (src/index.* via moduleFileExtensions), appBuild (build/), dotenv (.env), and testsSetup (src/setupTests). moduleFileExtensions lists web.mjs, mjs, web.js, js, web.ts, ts, web.tsx, tsx, json, web.jsx, jsx.
- env.js loads dotenv files in priority order: .env.${NODE_ENV}.local, .env.local (skipped when NODE_ENV is test), .env.${NODE_ENV}, .env. It then builds the raw public env object containing NODE_ENV, PUBLIC_URL, WDS_SOCKET_*, FAST_REFRESH, and every key matching /^REACT_APP_/i. Those are stringified for webpack DefinePlugin as process.env.KEY.
- webpack.config.js is a function (webpackEnv) => config. In production, mode is production, devtool is source-map unless GENERATE_SOURCEMAP=false, and output filenames include contenthash. In development, filenames are unhashed and devtool is cheap-module-source-map. output.publicPath comes from paths.publicUrlOrPath.
- HTML path: HtmlWebpackPlugin reads public/index.html. InterpolateHtmlPlugin substitutes %PUBLIC_URL% and other env placeholders. MiniCssExtractPlugin extracts CSS only in production; style-loader injects CSS in development. TerserPlugin and CssMinimizerPlugin minify in production.
- ModuleScopePlugin restricts imports that resolve outside src/ (and node_modules exceptions) so a user cannot accidentally import files from outside the project source tree via relative paths. babel-loader includes paths.appSrc only.
- Jest config from createJestConfig sets roots to <rootDir>/src, testMatch to the standard CRA patterns, transform for js/jsx/ts/tsx via babel-jest and for css/files via custom transformers in react-scripts/config/jest, moduleNameMapper for CSS and asset stubs, and setupFilesAfterEnv pointing at src/setupTests if it exists.
- The TypeScript data path is fork-ts-checker-webpack-plugin (async typecheck) when tsconfig.json or jsconfig.json exists, plus babel-preset-react-app's TypeScript preset when the file extension is ts/tsx. ESLint uses @typescript-eslint/parser only if the user has installed it (resolved via require.resolve with a fallback).
- Error overlay data flow: webpack compile errors and runtime errors are formatted by react-dev-utils/formatWebpackMessages and react-error-overlay. webpackHotDevClient listens on the dev-server websocket and calls into the overlay iframe. Source maps are consumed by @babel/code-frame and a StackFrame parser.
- Production output boundary is paths.appBuild (build/). public/ files are copied with fs.copySync excluding index.html. The build script writes no server; deployment is a static host. Docs describe this and netlify.toml is only for the documentation site, not for generated apps.
Behavior traces
Three end-to-end traces matter: creating an app, starting the dev server, and producing a production build. A fourth shorter trace is the Jest test command and a fifth is eject. Each names the functions in call order as they appear in the source.
- Startup trace (npx create-react-app my-app --template typescript): index.js checks node version -> calls run() in createReactApp.js -> parses argv into program flags -> createApp(name, verbose, scriptsVersion, template, usePnp) -> validates app name with validate-npm-package-name -> makes the directory -> writes a temporary package.json -> installs react, react-dom, react-scripts, and the template package via spawn of npm/yarn -> executeNodeScript(react-scripts/scripts/init.js) with JSON argv.
- init.js trace: verify node and react-scripts version compatibility -> copy template files from template/template into the app root -> merge template.json -> rename gitignore -> delete template package leftovers -> run git init, git add, git commit if git is available and the directory is not already a repo -> print Next steps (cd, npm start, npm test, npm run build, npm run eject). On failure it attempts to remove the created directory unless the user used . as the name.
- Dev server trace (npm start -> react-scripts start): start.js sets BABEL_ENV=development and NODE_ENV=development -> require('../config/env') -> checkRequiredFiles([appHtml, appIndexJs]) exits 1 if missing -> checkBrowsers(appPath) reads browserslist -> choosePort(HOST, DEFAULT_PORT 3000) -> configFactory('development') -> createCompiler({config, appName, urls, useYarn, useTypeScript, webpack}) -> prepareProxy(package.json proxy, appPublic, HOST) -> createDevServerConfig -> new WebpackDevServer -> devServer.startCallback -> openBrowser(urls.localUrlForBrowser) -> listen for stdin end and signals to gracefully shutdown.
- Compiler hook trace inside createCompiler: compiler.hooks.invalid, beforeCompile, and done. On done, formatWebpackMessages splits errors and warnings; TSC errors are appended when useTypeScript; if errors exist, printBuildError-style instructions are shown and the dev server keeps running. Successful compiles clear the console (unless COMPILER_TERMINAL is set or CI) and print the local and network URLs.
- Production build trace: build.js sets NODE_ENV=production -> checkRequiredFiles -> checkBrowsers -> measure file sizes of existing build/ -> fs.emptyDirSync(paths.appBuild) -> copyPublicFolder() -> build(previousFileSizes) which returns a Promise around webpack(configFactory('production')).run -> formatWebpackMessages -> if errors, reject and print the first error only -> resolve with stats, warnings, previous sizes -> printFileSizesAfterBuild -> printHostingInstructions(appPackage, publicUrl, publicPath, buildFolder, useYarn).
- Test trace: test.js sets BABEL_ENV=test and NODE_ENV=test -> env.js loads .env.test and .env but not .env.local -> argv is rewritten so that --watch is added when stdin is a TTY and CI is unset, or --watchAll when --coverage is passed without an explicit watch flag -> require('jest').run(argv). createJestConfig resolves transformers relative to react-scripts so ejected apps can retarget them.
- Eject trace: eject.js confirms prompt (unless CI) -> verifies git clean via git status --porcelain -> copies config/ and scripts/ from react-scripts into the app -> rewrites package.json dependencies by inlining react-scripts' own deps minus the blacklist -> replaces script entries -> removes react-scripts -> writes config files with a generated header comment. This is the documented escape hatch before 'alternatives to ejecting'.
- Template render trace for the default app: public/index.html is the HTML shell -> src/index.js imports React, ReactDOM, ./index.css, App, and reportWebVitals -> creates a root on document.getElementById('root') and renders <App /> -> App.js returns the header/logo/link tree -> App.test.js uses React Testing Library render and screen.getByText(/learn react/i).
- Browserslist gate: before start or build, checkBrowsers prompts (or fails in CI) when the browserslist config in package.json targets browsers that would pull in extra polyfills or when the default CRA browserslist is missing. Default template browserslist is production >0.2%, not dead, not op_mini all and development last 1 chrome/firefox/safari version.
- Fast Refresh path: when FAST_REFRESH is not false, webpack entry includes the React Refresh client and babel-preset-react-app enables react-refresh/babel in development. webpackHotDevClient.js is still the CRA client that reports compile status; React Refresh handles component state-preserving updates separately from full reloads.
- --scripts-version path: if the user passes a version, tarball URL, or file: path, createReactApp installs that instead of the bundled react-scripts dependency. A custom fork must still expose scripts/init.js because executeNodeScript hard-codes that relative path inside the installed package.
Testing signals
Tests are split across package-level Jest unit tests and a fixture integration suite under test/ that builds real apps with the local react-scripts. The root test script runs tasks/e2e-simple.sh; full behavior coverage is tasks/e2e-behavior.sh and tasks/e2e-docker.sh. GitHub Actions runs these on pull requests. Unit tests use Jest; a few packages still mention Flow. There is no Cypress/Playwright app suite — e2e here means CLI integration against webpack builds. Coverage of the dev server, eject, and the docs site is thin compared with the fixture build matrix.
- Root package.json test script is node tasks/e2e-simple.sh. The e2e script is node tasks/e2e-simple.sh && node tasks/e2e-behavior.sh. e2e:docker is node tasks/e2e-docker.sh. There is no root jest.config; each package runs Jest via its own npm test or via the integration runner.
- react-dev-utils tests live in packages/react-dev-utils/__tests__ and cover WebpackDevServerUtils, formatWebpackMessages, ModuleScopePlugin, and browsersHelper-style helpers. The package test script is jest.
- babel-plugin-named-asset-import and confusing-browser-globals each expose an npm test script (Jest or node test runner as declared). babel-preset-react-app fixtures under its package test directory compile sample files with the preset and snapshot or assert output.
- react-error-overlay has its own Jest + jsdom setup and a webpack build (build, build:prod). Tests render the overlay iframe and stack-frame parser. A Flow annotation path remains (npm run flow) even though most of the repo is plain JS.
- Template unit test App.test.js only asserts that the learn-react link renders. It does not cover index.js boot, web-vitals, or CSS. The kitchen-sink behavior of webpack loaders is instead covered by test/fixtures compiled during e2e.
- GitHub Actions build-and-test.yml checks out the repo, sets up Node, enables corepack/yarn, installs, and builds the local tarballs via tasks/build.js style steps before e2e. e2e-base.yml is a reusable workflow_call so the docker e2e job can share steps. lint.yml runs the eslint script.
- eslint is a first-class check: root script eslint runs on packages and tasks. .eslintrc.json extends the local eslint-config-react-app (or a root config that points at it) and prettier is enforced via .prettierrc. The format script writes; CI lint does not auto-fix.
- What is lightly tested: eject.js has historical integration coverage but is not part of e2e-simple's critical path; the Docusaurus site has no automated visual or link test in the workflows read; WebpackDevServer HTTPS, proxy, and host-check branches are mostly untested outside manual QA; react-app-polyfill has no behavioral browser matrix in CI. (inferred)
Risk map
The highest-risk surfaces are process spawning during install (npm/yarn), the dev server's host check and proxy, env inlining, and eject rewriting package.json. Secrets are not stored in-repo; the dangerous pattern is REACT_APP_* being baked into the client bundle. Several code paths shell out to git. The project is in maintenance mode (v5.1.0) so dependency CVEs in webpack 5 / Jest 27 will linger unless backporting continues. Dead weight includes IE polyfill entrypoints and Flow leftovers.
- createReactApp.js spawns the package manager (npm, yarn, or pnpm when use-pnp) with user-influenced package specifiers (--scripts-version and --template). Specifiers are passed as arguments (not a shell string) in the spawn path, but a malicious --scripts-version file: URL or git URL can still execute that package's install scripts. This is inherent to any scaffolder.
- executeNodeScript writes a temporary JS file and runs it with the Node binary to invoke init.js, passing serialized arguments. The temp file is removed afterwards. If cwd or the template path were attacker-controlled beyond the CLI user, this is an arbitrary Node execution primitive — acceptable for a local CLI, unsafe if wrapped as a service.
- Dev server host check: allowedHosts is set to all when DANGEROUSLY_DISABLE_HOST_CHECK=true, which re-opens DNS-rebinding exposure against the webpack-dev-server. Proxy middleware (http-proxy-middleware) forwards to package.json proxy and can be abused if a malicious site is allowed to hit the dev server. sockHost/sockPath/sockPort (WDS_SOCKET_*) are also env-controlled.
- env.js documents and implements that any REACT_APP_* variable is embedded into the JS bundle via DefinePlugin. Putting secrets in REACT_APP_ keys ships them to every browser. .env.local is loaded for development and production but intentionally skipped for test.
- init.js and eject.js invoke git (init, add, commit, status) through cross-spawn or execSync. A hostile git hook in an existing repo (eject) or a strange GIT_* environment can run code. eject refuses a dirty tree unless forced, which is a safety check not a security boundary.
- HTTPS dev server: when HTTPS=true, start.js / webpackDevServer.config.js enables https. Certificate handling uses webpack-dev-server defaults (self-signed) unless SSL_CRT_FILE and SSL_KEY_FILE are set. Those paths are read from disk; a wrong path fails the start rather than falling back silently in the config that reads them.
- ModuleScopePlugin and the image inline size limit are integrity features, not auth. There is no authentication layer anywhere: CRA generates static SPAs. Anyone who treats the dev server as an authenticated backend proxy inherits the proxy's lack of CSRF protection.
- Dependency blast radius is react-scripts/package.json: webpack, webpack-dev-server, Jest, babel, eslint, postcss, and workbox are pinned to the v5 line (webpack 5, Jest 27, ESLint 8). A vulnerability in webpack-dev-server affects every app that has not ejected. Ejected apps freeze a copy and stop receiving fixes.
- IE compatibility code (react-app-polyfill/js/ie11.js and ie9) and confusing-browser-globals are legacy surfaces. They still ship because older generated apps import them. Changing the globals list is a breaking ESLint change for every consumer of eslint-config-react-app.
- eslint-config-react-app uses try/catch require.resolve to optionally enable TypeScript, Jest, and Testing Library rules. If those plugins are installed but at an incompatible major, ESLint crashes the build/start because CRACO-less CRA fails compilation on ESLint errors (ESLINT_NO_DEV_ERRORS can soften dev). That coupling is a frequent break when users upgrade plugins independently.
- The docs site and the published README can drift from the code. available-scripts.md and adding-custom-environment-variables.md are the contract users trust. netlify.toml only publishes the website; a docs-only claim about runtime behavior must be checked against packages/react-scripts before editing code.
- CI docker e2e is the only place the full behavior matrix runs. A change to webpack.config.js or env.js can pass unit tests and e2e-simple yet break typescript fixtures or PUBLIC_URL handling. Those fixtures are the regression net. (inferred)
Extension points
CRA's extension model is deliberate and narrow: custom templates, a replaceable react-scripts package (--scripts-version), env vars, package.json fields (proxy, homepage, browserslist, jest, babel), and finally eject. There is no in-process plugin registry. The practical plug-in points inside the repo are the webpack config factory, the Jest config factory, babel-preset-react-app's create() options, and ESLint's optional plugin detection. Community tools (CRACO, react-app-rewired) patch these from outside because the project refuses a first-party override API.
- Templates are the supported product extension. A template package must be named cra-template-* (or scoped) and contain template.json plus a template/ directory. template.json keys merged by init.js are package.json fields: dependencies, scripts, eslintConfig, babel, jest, browserslist. Any extra files under template/ are copied verbatim.
- --scripts-version replaces the entire toolchain package. A fork must provide bin/react-scripts.js and scripts/init.js, start.js, build.js, test.js. The CLI does not feature-detect; it only installs and executes init.js.
- webpack.config.js exports a factory function of webpackEnv. Internal extension is editing that factory (or ejecting a copy). There is no plugins array exposed to package.json. Advanced-configuration docs point users at environment variables rather than a config file.
- Environment extension surface (read by env.js and start.js): PORT, HOST, HTTPS, SSL_CRT_FILE, SSL_KEY_FILE, BROWSER, BROWSER_ARGS, PUBLIC_URL, BUILD_PATH, GENERATE_SOURCEMAP, INLINE_RUNTIME_CHUNK, IMAGE_INLINE_SIZE_LIMIT, FAST_REFRESH, CHOKIDAR_USEPOLLING, TSC_COMPILE_ON_ERROR, ESLINT_NO_DEV_ERRORS, DISABLE_ESLINT_PLUGIN, DISABLE_NEW_JSX_TRANSFORM, WDS_SOCKET_HOST, WDS_SOCKET_PATH, WDS_SOCKET_PORT, DANGEROUSLY_DISABLE_HOST_CHECK, CI, and REACT_APP_*.
- package.json fields honored without eject: proxy (string or object consumed by prepareProxy), homepage (feeds publicPath via paths.js), browserslist, and optional jest/babel overrides that get merged but are only partially respected — createJestConfig ignores most user keys unless they were written by eject. Users commonly discover this limitation.
- babel-preset-react-app's create(options) is the Babel extension point inside the monorepo. webpack and Jest both call it with absoluteRuntime, flow flags, and helpers. babel-plugin-named-asset-import is injected here so SVG ReactComponent imports work. Custom presets in the app are not loaded unless the user ejects or replaces the preset.
- ESLint extension is eslintConfig in package.json of the generated app, which extends react-app and optionally react-app/jest. Adding rules works; changing the parser for TS is automatic only when typescript and the parser package are installed. The config file exports a function so it can conditionally require plugins.
- Jest transformers are extension points for non-JS assets: cssTransform returns an empty module, fileTransform stringifies filenames (and special-cases SVG for ReactComponent). New asset types require a new transform plus a moduleNameMapper entry in createJestConfig.
- react-error-overlay is replaceable only by eject or by aliasing the module. It exposes a small runtime API (listen, report, dismiss, startReportingRuntimeErrors) used by webpackHotDevClient. Editing overlay UX means changing that package and rebuilding it (npm run build).
- Docusaurus docs extension is file-based: drop an md file in docusaurus/docs and add it to sidebars.json. swizzle script exists for theming. This does not affect the CLI.
- Supported alternatives to a plugin API, as documented, are: composing libraries inside src/, using a custom template, forking react-scripts, or ejecting. The docs page alternatives-to-ejecting.md is the product decision record: CRA will not grow an overrides config.
Contributor handoff
Edit the package that owns the behavior, not the docs site, unless the task is documentation. The CLI is packages/create-react-app; compiler behavior is packages/react-scripts/config and scripts; shared helpers are packages/react-dev-utils. Keep Node >=14 assumptions. Do not add a webpack-override API. Verify with the package's Jest tests first, then tasks/e2e-simple.sh for scaffold or config changes. Avoid npm install at the repo root unless the user asked — Yarn workspaces and tasks/build.js are the intended install/pack path. Generated template files are copied verbatim, so a template bug ships to every new app.
- Read order for any behavior change: packages/react-scripts/bin/react-scripts.js, the relevant scripts/*.js, config/paths.js, config/env.js, config/webpack.config.js, then the matching helper in packages/react-dev-utils. For scaffold bugs read createReactApp.js then scripts/init.js.
- CONTRIBUTING.md is the contributor contract: issues and PRs, how to run tests, and the expectation that changes stay focused. README.md states the user-facing quick start (npx create-react-app my-app) and points documentation at create-react-app.dev. Prefer updating both the code and the matching docusaurus/docs page when behavior changes.
- Safe, low-blast edits: a single fixture under test/fixtures, a doc page, template copy in packages/cra-template/template (remember the TS twin), or a unit test in __tests__. High-blast edits: webpack.config.js, env.js, createJestConfig.js, eslint-config-react-app/index.js, init.js merge logic, and package.json dependency bumps in react-scripts.
- Template edits must be applied to both packages/cra-template and packages/cra-template-typescript when the change is not JS-only. template.json dependency versions should stay aligned (react-scripts version field, testing-library, web-vitals). Forgetting the TS template is a known footgun.
- Tests to run: for react-dev-utils, npm test inside that package. For CLI parsing, npm test inside packages/create-react-app. For scaffold or webpack behavior, yarn test (tasks/e2e-simple.sh) from the root after tasks/build.js has packed local tarballs. Full matrix is yarn e2e. ESLint via yarn eslint. Prettier via the format script; do not reformat unrelated files.
- Node version gate is duplicated: create-react-app/index.js semver check and root package.json engines.node >=14. CI Node version must satisfy both. Do not use newer Node-only APIs (e.g. native fetch assumptions, import assertions) without updating the engines field and the runtime check.
- Do not hand-edit Yarn/npm lockfiles except as the result of an install the user requested. Do not bump webpack, Jest, or Babel majors casually: the e2e fixtures and babel-preset-react-app are tightly coupled to Jest 27 and Babel 7 APIs. Lerna version in lerna.json must stay consistent with published package versions.
- Trap: PUBLIC_URL vs homepage vs paths.publicUrlOrPath. Changing one without reading paths.js and InterpolateHtmlPlugin and the build.js hosting instructions will break asset URLs for apps hosted on a subpath. Trap: .env.local is ignored when NODE_ENV=test, so a test that depends on a local secret-looking var will pass locally in start and fail in Jest.
- Trap: DISABLE_ESLINT_PLUGIN, ESLINT_NO_DEV_ERRORS, TSC_COMPILE_ON_ERROR, and DISABLE_NEW_JSX_TRANSFORM are user escape hatches. A change that ignores them will break apps that opted out. Search for process.env consumers before refactoring start.js or webpack.config.js.
- Trap: init.js merge is a shallow Object.assign of dependency maps. A template that needs to remove a default dependency cannot do it by omission if the CLI preinstalls react-scripts. Read the install list in createReactApp.js and the merge in init.js together before changing the default dependency set.
- Coding style: Prettier is configured in .prettierrc and ESLint in .eslintrc.json. Existing files use CommonJS require, not ESM. react-error-overlay still has a build step — editing its src without running its build script leaves stale published assets. Flow annotations, if touched, should not be spread into CommonJS packages that do not run Flow.
- The repo is the upstream of a widely installed generator (create-react-app 5.1.0, react-scripts consumers in the millions historically). Prefer bug-fix diffs over API additions. Any new env var needs a docusaurus advanced-configuration entry or users will not find it. Do not deploy the docs site from a feature branch; Netlify publishes the configured site build.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 271 | 89% |
| Markdown | 75 | docs/config |
| JSON | 41 | docs/config |
| TypeScript | 14 | 5% |
| CSS | 12 | docs/config |
| Shell | 10 | 3% |
| Sass | 9 | 3% |
| YAML | 7 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (322 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/babel-preset-react-app/ | 10 |
packages/eslint-config-react-app/ | 6 |
packages/react-app-polyfill/ | 7 |
packages/react-dev-utils/ | 41 |
packages/react-error-overlay/ | 26 |
packages/react-scripts/ | 135 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 322 |
test/ | 78 |
docusaurus/ | 55 |
tasks/ | 15 |
.github/ | 11 |
Docs found: CONTRIBUTING.mdREADME.md
Package
package.json — , 23 declared dependencies.
@testing-library/jest-dom@testing-library/react@testing-library/user-eventalexeslintexecafs-extraget-portglobbyhuskyjestlerna
CI & config entrypoints
README.md— Repository readmetest/fixtures/typescript-advanced/src/App.tsx— React roottest/fixtures/typescript-typecheck/src/App.tsx— React rootpackages/cra-template-typescript/template/src/App.tsx— React root.github/workflows/build-and-test.yml— GitHub Actions workflow.github/workflows/lint.yml— GitHub Actions workflow.github/workflows/e2e-base.yml— GitHub Actions workflowpackage.json— npm scripts: alex, build, changelog, create-react-app, e2e, e2e:docker, eslint, formatdocusaurus/website/package.json— npm scripts: build, deploy, start, swizzlepackages/babel-plugin-named-asset-import/package.json— npm scripts: test
Structural health signals
Average score 7.9/10 across 96 analyzed source files; 3 hotspots surfaced.
packages/create-react-app/createReactApp.js— 1155 lines, score 4.7 (Large file, Deep nesting)packages/react-scripts/config/webpack.config.js— 796 lines, score 5.5 (Large file, Deep nesting)packages/react-scripts/scripts/eject.js— 345 lines, score 6.4 (Deep nesting, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
6254386531d22025-02-14 — Publishb961be37929c2025-02-14 — Add deprecation to website (#17008)3800660411062025-02-14 — Update deprecation link (#17015)b532a58792ea2025-01-28 — Deprecate Create React App officially by changing the README, and adding a message on init (#17003)fde66a29e3c22025-01-28 — Merge pull request #13738 from MatanBobi/chores/update-rtl-version-rtl-16