React Transform Catch Errors

Common errors

• Error: Cannot find module 'babel-plugin-react-transform'

  cause The essential `babel-plugin-react-transform` package, which orchestrates this transform, is not installed.
  fix Install it as a development dependency: `npm install --save-dev babel-plugin-react-transform`.

• Uncaught Error: imports[1] for react-transform-catch-errors does not look like a React component.

  cause This error typically indicates a version mismatch between `react-transform-catch-errors`, `redbox-react`, or related `react-transform` packages, or an incorrect path to the error reporter.
  fix Ensure `react-transform-catch-errors`, `redbox-react`, and `babel-plugin-react-transform` are installed with compatible versions. Try removing caret (`^`) from version numbers in `package.json`, clearing npm cache (`npm cache clean --force`), deleting `node_modules`, and reinstalling (`npm install`). Verify the path to your error reporter in `.babelrc` is correct and resolvable.

• Production bundle includes development-only error catching logic, increasing bundle size.

  cause The `react-transform-catch-errors` configuration is not scoped to the `development` environment in your `.babelrc` file.
  fix Wrap the `react-transform` plugin configuration inside an `env.development` block in your `.babelrc` to ensure it's only active when `process.env.NODE_ENV` is set to 'development'.

Warnings

• breaking Starting with v1.0.0, this transform no longer acts as a no-op in production environments. It is now explicitly your responsibility to ensure it's only enabled in development builds.
  Fix: Wrap your `react-transform` configuration within an `env.development` block in your `.babelrc` to prevent it from being included in production builds. Ensure `process.env.NODE_ENV` is correctly set during your build process.
• deprecated The `react-transform` ecosystem, including `react-transform-catch-errors`, is largely abandoned and superseded by modern React development tools such as React Fast Refresh (introduced with React 17) and built-in React Error Boundaries. Using this package in new projects is not recommended.
  Fix: For error handling, migrate to React Error Boundaries (class components with `static getDerivedStateFromError` or `componentDidCatch`). For an improved development experience, ensure your build setup supports React Fast Refresh, which offers superior hot reloading and error recovery.
• gotcha This package requires `babel-plugin-react-transform` to function, as it's a transform *for* that plugin, not a standalone Babel plugin. It also requires a separate error reporter package (e.g., `redbox-react`) to display errors.
  Fix: Ensure both `babel-plugin-react-transform` and your chosen error reporter (e.g., `redbox-react`) are installed as `devDependencies` and correctly configured in your `.babelrc`.
• gotcha Errors in event handlers, asynchronous code (e.g., `setTimeout`), server-side rendering, or within the error boundary component itself are not caught by this transform or even native React Error Boundaries.
  Fix: Implement traditional JavaScript `try-catch` blocks for asynchronous code and event handlers where error handling is critical. For server-side rendering, separate error logging mechanisms are required.

Install

• npm install react-transform-catch-errors npm
• yarn add react-transform-catch-errors yarn
• pnpm add react-transform-catch-errors pnpm

Imports

• "react-transform-catch-errors"
  wrong:

  import { catchErrors } from 'react-transform-catch-errors';
  const catchErrors = require('react-transform-catch-errors');

  correct:

  // Configured as a string in your .babelrc, not directly imported in JS

  This package is a Babel transform and is never directly imported into application JavaScript or TypeScript code. It is referenced as a string literal within your `.babelrc` configuration under the `babel-plugin-react-transform` plugin's `transforms` array. The transform itself then operates on your component code at compile time.
• "react"
  wrong:

  import React from 'react-transform-catch-errors/react';

  correct:

  // Configured as a string in your .babelrc transforms.imports array

  When configuring `react-transform-catch-errors` in `.babelrc`, the first item in the `imports` array (e.g., "react" or "react-native") specifies your React distribution. This tells the transform which React runtime to use for its internal operations, it is not an import *from* `react-transform-catch-errors`.
• "redbox-react"
  wrong:

  import Redbox from 'react-transform-catch-errors/redbox-react';

  correct:

  // Configured as a string in your .babelrc transforms.imports array

  The second item in the `imports` array within the `.babelrc` configuration specifies the module that will render the error component (e.g., "redbox-react" or a path to your custom error reporter). This module is dynamically loaded by the transform, not by your application code directly.

Quickstart

This `.babelrc` configuration demonstrates how to enable and configure `react-transform-catch-errors` for development environments, specifying 'react' as the runtime and 'redbox-react' as the error display component.

{
  "presets": ["es2015", "stage-0"],
  "env": {
    // Only enable in development environment
    "development": {
      "plugins": [
        [
          "react-transform",
          {
            "transforms": [
              {
                "transform": "react-transform-catch-errors",
                "imports": [
                  "react",
                  "redbox-react"
                  // Optional third import for reporter options:
                  // , "./my-reporter-options"
                ]
              }
              // Add other react-transforms here if needed, e.g., react-transform-hmr
            ]
          }
        ]
      ]
    }
  }
}