babel-plugin-react-transform

3.0.0 verified Sat Apr 25 auth: no javascript deprecated

This Babel plugin wraps React components with arbitrary transforms, enabling instrumentation like hot reloading, error catching, and render logging. Current stable version is 3.0.0 (Babel 6 support). It was deprecated in favor of React Hot Loader 3 and should not be used in new projects. The plugin is part of a highly experimental ecosystem; its API changed between v1.x and v2.x, with the `target` option renamed to `transform` and the config moved under a `transforms` property. Alternatives include React Hot Loader 3 and newer tools like Fast Refresh.

Common errors

error ReferenceError: regeneratorRuntime is not defined ↓

cause Babel 6 does not include runtime polyfills by default; you need to configure the 'transform-runtime' or 'babel-polyfill' plugin.

fix

Add 'babel-plugin-transform-runtime' to your Babel plugins, or import 'babel-polyfill' in your entry file.

error Module not found: Can't resolve 'react-transform-hmr' ↓

cause The required transform package is not installed or not in node_modules.

fix

Run 'npm install --save-dev react-transform-hmr' (or the specific transform you need).

error Uncaught TypeError: Cannot read property 'find' of undefined ↓

cause An older polyfill (like bad version of lodash) breaks Array#find, which the plugin uses internally in v2.0.2.

fix

Update to babel-plugin-react-transform@2.0.2 or later, or ensure a proper polyfill for Array.prototype.find.

Warnings

deprecated This project is deprecated. React Hot Loader 3 is the replacement, and React Fast Refresh is the modern solution. ↓

fix Migrate to React Fast Refresh (built into Create React App, Next.js, etc.) or react-hot-loader@3+.

breaking In v2.0.0, the config format changed: 'target' was renamed to 'transform', and the array of transforms is now under a 'transforms' property on the plugin options object instead of 'extra'. ↓

fix Update your .babelrc from the v1 format: remove 'extra', add plugin options directly with 'transforms' array and use 'transform' instead of 'target'.

breaking v2.0.1 fixed false positives: only components with a 'render' method AND subclassing one of 'options.superClasses' (default: React.Component) or using 'options.factoryMethods' (default: React.createClass) are instrumented. ↓

fix If your components are not being wrapped, ensure they extend a recognized superclass or are created via factory methods, or configure 'superClasses'/'factoryMethods' in plugin options.

gotcha The plugin is highly experimental and may be incompatible with future React or Babel versions. It has known issues with circular imports and Array#find polyfills in older environments. ↓

fix Avoid using this plugin in production. For hot reloading, use React Hot Loader 3 or Fast Refresh. For error catching, prefer React error boundaries.

Install

npm install babel-plugin-react-transform

yarn add babel-plugin-react-transform

pnpm add babel-plugin-react-transform

Imports

default
wrong
```
const reactTransform = require('babel-plugin-react-transform')
```
correct
```
import reactTransform from 'babel-plugin-react-transform'
```
Babel plugins are typically used via .babelrc or babel.config.js, not imported directly. The 'require' form works in Node but is not the expected usage.

plugin (as Babel config)

wrong

{
  "plugins": ["react-transform"],
  "extra": {
    "react-transform": [{
      "target": "react-transform-hmr",
      "imports": ["react"]
    }]
  }
}

correct

{
  "plugins": ["react-transform"],
  "env": {
    "development": {
      "plugins": [["react-transform", {
        "transforms": [{
          "transform": "react-transform-hmr",
          "imports": ["react"]
        }]
      }]]
    }
  }
}

The old config format (v1.x) used 'extra' and 'target'. v2+ uses 'transforms' array and 'transform' property inside the plugin options.

transform module (e.g., react-transform-hmr)
wrong
```
const hmrTransform = require('react-transform-hmr')
```
correct
```
import hmrTransform from 'react-transform-hmr'
```
Transform modules are CommonJS compatible but ESM import works if they export a default. Most transforms export a function or object and can be imported.

Quickstart

Shows how to install and configure babel-plugin-react-transform with a transform, including Babel 6 env-specific config.

// First, install the plugin and a transform:
// npm install --save-dev babel-plugin-react-transform react-transform-hmr

// Then, configure Babel (e.g., in .babelrc or babel.config.js):
// For Babel 6, add the plugin under 'env.development' to only apply in dev:
{
  "presets": ["react"],
  "env": {
    "development": {
      "plugins": [["react-transform", {
        "transforms": [{
          "transform": "react-transform-hmr",
          "imports": ["react-dom"]
        }]
      }]]
    }
  }
}

// Note: This plugin is deprecated. Prefer React Hot Loader 3 or Fast Refresh.