Babel Preset for Create React App

Common errors

• Error: Cannot find module '@babel/preset-env'

  cause This preset relies on `@babel/preset-env` and other Babel plugins. If you're using this preset outside of a Create React App context without a proper Babel setup, these peer dependencies might not be installed.
  fix Ensure `@babel/core`, `babel-loader`, and `babel-preset-react-app` are installed as `devDependencies`. If you are manually managing Babel dependencies, verify all necessary presets and plugins (e.g., `@babel/preset-env`, `@babel/plugin-proposal-class-properties`) are installed and correctly configured in your `package.json` and `.babelrc`.

• Objects are not valid as a React child (found: object with keys {$$typeof, type, key, ref, props, _owner}). If you meant to render a collection of children, use an array instead.

  cause This error often occurs in React 17+ projects when an older Babel configuration or `babel-preset-react-app` version is used that doesn't fully support the new JSX transform. It indicates an issue with how JSX is being compiled.
  fix Ensure your `react` and `react-dom` packages are at least `17.0.0` and that `react-scripts` is updated to at least `4.0.0` (or `babel-preset-react-app` to `4.0.0`) to leverage the new JSX transform. Verify your `.babelrc` file does not override or disable the necessary JSX transform options.

• Support for the experimental syntax 'classProperties' isn't currently enabled

  cause While `babel-preset-react-app` includes support for class properties, this error can occur if another Babel configuration or a Webpack loader is processing the files *before* or *after* this preset in a way that interferes, or if an outdated version is used.
  fix Check your Babel configuration order if you have multiple presets/plugins. Ensure `babel-preset-react-app` is applied correctly. If using `react-scripts`, make sure you haven't ejected and introduced conflicting Babel configurations. Update `react-scripts` to the latest version.

• TypeScript error: 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.

  cause This typically happens in TypeScript projects when the `isolatedModules` compiler option is enabled, and a file uses JSX without explicitly importing `React` (which is no longer necessary with the new JSX transform in React 17+). The TypeScript compiler still needs to understand the `React` reference if `isolatedModules` is on.
  fix You can either: 1) Add `import React from 'react';` at the top of your TypeScript files if `isolatedModules` is enabled. 2) Set the `jsx` compiler option in `tsconfig.json` to `'react-jsx'` or `'react-jsxdev'` for React 17+ projects, which informs TypeScript about the new JSX transform and removes the need for explicit `React` imports.

Warnings

• breaking Create React App 5.0 (which uses babel-preset-react-app v5.0.0+) upgraded major dependencies including Webpack 5, Jest 27, ESLint 8, and PostCSS 8. This may introduce breaking changes in custom configurations or specific tooling integrations that rely on older versions of these dependencies.
  Fix: Review your project's `package.json` and any custom configuration files (`webpack.config.js`, `.eslintrc.js`, `jest.config.js`) for compatibility with the new major versions. Update any plugins or loaders that might conflict.
• breaking Create React App 4.0 (using babel-preset-react-app v4.0.0+) introduced support for the New JSX Transform from React 17. While generally backwards compatible, it changes how JSX is compiled and removes the need to `import React from 'react'` at the top of every file containing JSX.
  Fix: For existing projects, ensure you are on React 17+. You can safely remove `import React from 'react';` from component files, although leaving it will not cause issues. If you have custom Babel setups, ensure `@babel/plugin-transform-react-jsx` is configured correctly, or rely on this preset.
• gotcha By default, `babel-preset-react-app` uses `absoluteRuntime: true` for Babel helper imports. If you need relative paths for some advanced scenarios (e.g., specific monorepo setups or environments with non-standard module resolution), you must explicitly configure it.
  Fix: To use relative paths, set the `absoluteRuntime` option to `false` in your `.babelrc` or Babel configuration file: `["react-app", { "absoluteRuntime": false }]`.
• gotcha This preset is intended for use with Create React App projects. While it can be used independently, it is highly opinionated and may conflict with other custom Babel configurations or require additional polyfills that CRA typically handles. It assumes a specific environment and tooling setup.
  Fix: If using outside of CRA, ensure you have `@babel/core`, `react`, and any necessary polyfills (`core-js`) installed and configured correctly. For highly customized projects, consider using more granular Babel presets like `@babel/preset-env` and `@babel/preset-react` directly.
• deprecated The documentation excerpt refers to `babel-preset-react-app` handling vulnerability fixes for dependencies like `resolve-url-loader`, `webpack-dev-server`, and `terser-webpack-plugin` in older versions (e.g., v3.4.x). While these specific issues might be resolved, it highlights that relying on old versions of this preset (and thus old CRA versions) could expose projects to unpatched vulnerabilities in its underlying dependencies.
  Fix: Always keep your `react-scripts` package (and by extension, `babel-preset-react-app`) updated to the latest stable version to benefit from bug fixes, performance improvements, and security patches for its bundled dependencies. Run `npm install --save --save-exact react-scripts@latest` or `yarn add --exact react-scripts@latest`.

Install

• npm install babel-preset-react-app npm
• yarn add babel-preset-react-app yarn
• pnpm add babel-preset-react-app pnpm

Imports

• preset
  wrong:

  import preset from 'babel-preset-react-app'

  correct:

  { "presets": ["react-app"] }

  This package is a Babel preset and is configured in a .babelrc or babel.config.js file, not imported directly into application code. The value 'react-app' refers to the preset itself.
• typescript config

  { "presets": [["react-app", { "typescript": true }]] }

  To enable TypeScript support within the preset, pass an options object with `typescript: true`. This assumes a `tsconfig.json` file is present in the project root.
• flow config

  { "presets": [["react-app", { "flow": true, "typescript": false }]] }

  To enable Flow support, pass an options object with `flow: true`. Ensure you have a `.flowconfig` file. TypeScript and Flow options are mutually exclusive.

Quickstart

Demonstrates the basic `.babelrc` configuration for `babel-preset-react-app`, including options for TypeScript and absolute runtime paths. This file should be in your project root.

{
  "presets": [
    [
      "react-app",
      {
        "flow": false,
        "typescript": true, // Set to true if using TypeScript, false otherwise.
        "absoluteRuntime": true // Use absolute paths for Babel helper imports
      }
    ]
  ]
}

// Example React component in src/App.tsx (if typescript: true)
// import React from 'react';

// const App: React.FC = () => {
//   const [count, setCount] = React.useState(0);
//   const increment = () => setCount(prev => prev + 1);

//   return (
//     <div>
//       <h1>Hello from React App!</h1>
//       <p>Count: {count}</p>
//       <button onClick={increment}>Increment</button>
//     </div>
//   );
// };

// export default App;