CodeVetter · Repo Unpack · Contributor handoff
react/create-react-app
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.