Babel Plugin

The babel-plugin-react-compiler package is the primary interface for transforming React code with automatic memoization.

Installation

npm install --save-dev babel-plugin-react-compiler

yarn add --dev babel-plugin-react-compiler

pnpm add -D babel-plugin-react-compiler

Basic Setup

Babel Configuration

module.exports = {
  presets: ['@babel/preset-react'],
  plugins: [
    'babel-plugin-react-compiler',
  ],
};

{
  "presets": ["@babel/preset-react"],
  "plugins": ["babel-plugin-react-compiler"]
}

{
  "presets": ["@babel/preset-react"],
  "plugins": ["babel-plugin-react-compiler"]
}

Plugin Options

Pass configuration options as the second element in the plugin array:

babel.config.js

module.exports = {
  plugins: [
    [
      'babel-plugin-react-compiler',
      {
        // Options here
        environment: {
          validateHooksUsage: true,
          enablePreserveExistingMemoizationGuarantees: true,
        },
      },
    ],
  ],
};

Option Structure

interface PluginOptions {
  // Environment configuration (compiler behavior)
  environment?: EnvironmentConfig;
  
  // Logging interface
  logger?: Logger;
  
  // Compilation mode
  mode?: 'all_features' | 'no_inferred_memo';
  
  // Opt-in/opt-out configuration
  sources?: (filename: string) => 'all' | 'none' | 'opt-in' | 'opt-out';
  
  // Enable Reanimated integration check
  enableReanimatedCheck?: boolean;
}

Compilation Modes

Compile All Components

By default, the compiler attempts to compile all components and hooks:

module.exports = {
  plugins: [
    'babel-plugin-react-compiler',
  ],
};

Opt-In Mode

Only compile components with "use memo" directive:

babel.config.js

module.exports = {
  plugins: [
    [
      'babel-plugin-react-compiler',
      {
        sources: (filename) => {
          // Opt-in for specific directories
          if (filename.includes('src/components')) {
            return 'opt-in';
          }
          return 'none';
        },
      },
    ],
  ],
};

Mark components for compilation:

function MyComponent(props) {
  'use memo';
  // Component code
}

Opt-Out Mode

Compile everything except components with "use no memo" directive:

babel.config.js

module.exports = {
  plugins: [
    [
      'babel-plugin-react-compiler',
      {
        sources: (filename) => {
          return 'opt-out';
        },
      },
    ],
  ],
};

Skip specific components:

function ProblematicComponent(props) {
  'use no memo';
  // Component code that shouldn't be compiled
}

File-Based Configuration

babel.config.js

module.exports = {
  plugins: [
    [
      'babel-plugin-react-compiler',
      {
        sources: (filename) => {
          // Don't compile test files
          if (filename.includes('__tests__')) {
            return 'none';
          }
          
          // Opt-in for new features
          if (filename.includes('src/features/new')) {
            return 'opt-in';
          }
          
          // Opt-out for legacy code
          if (filename.includes('src/legacy')) {
            return 'opt-out';
          }
          
          // Compile all others
          return 'all';
        },
      },
    ],
  ],
};

Build Tool Integration

Webpack

Integrate with babel-loader:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-react',
              '@babel/preset-typescript',
            ],
            plugins: [
              [
                'babel-plugin-react-compiler',
                {
                  environment: {
                    validateHooksUsage: true,
                  },
                },
              ],
            ],
            cacheDirectory: true, // Enable caching
          },
        },
      },
    ],
  },
};

Vite

Configure with @vitejs/plugin-react:

vite.config.js

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: [
          [
            'babel-plugin-react-compiler',
            {
              environment: {
                enableOptionalDependencies: true,
              },
            },
          ],
        ],
      },
    }),
  ],
});

Next.js

Next.js 13.5+ has built-in support:

next.config.js

const nextConfig = {
  experimental: {
    reactCompiler: {
      // Compiler options
      enablePreserveExistingMemoizationGuarantees: true,
    },
  },
};

module.exports = nextConfig;

For older versions, use custom Babel config:

.babelrc

{
  "presets": ["next/babel"],
  "plugins": [
    [
      "babel-plugin-react-compiler",
      {
        // options
      }
    ]
  ]
}

Create React App

Use react-app-rewired or craco:

module.exports = {
  babel: {
    plugins: [
      [
        'babel-plugin-react-compiler',
        {
          environment: {
            validateHooksUsage: true,
          },
        },
      ],
    ],
  },
};

const { override, addBabelPlugin } = require('customize-cra');

module.exports = override(
  addBabelPlugin([
    'babel-plugin-react-compiler',
    {
      // options
    },
  ])
);

Rollup

Use with @rollup/plugin-babel:

rollup.config.js

import babel from '@rollup/plugin-babel';

export default {
  plugins: [
    babel({
      babelHelpers: 'bundled',
      presets: ['@babel/preset-react'],
      plugins: [
        [
          'babel-plugin-react-compiler',
          {
            // options
          },
        ],
      ],
    }),
  ],
};

esbuild

Use with esbuild-plugin-babel:

build.js

const esbuild = require('esbuild');
const babel = require('esbuild-plugin-babel');

esbuild.build({
  entryPoints: ['src/index.jsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    babel({
      filter: /\.(js|jsx|ts|tsx)$/,
      config: {
        presets: ['@babel/preset-react'],
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
  ],
});

Custom Logger

Implement custom logging for compiler events:

babel.config.js

class CustomLogger {
  logEvent(filename, event) {
    if (event.kind === 'CompileSuccess') {
      console.log(`✓ Compiled: ${event.fnName} in ${filename}`);
    } else if (event.kind === 'CompileError') {
      console.error(`✗ Error in ${filename}:`, event.error);
    }
  }
  
  debugLogIRs(value) {
    // Log intermediate representations
    if (value.kind === 'hir') {
      console.log('HIR:', value.name);
    }
  }
}

module.exports = {
  plugins: [
    [
      'babel-plugin-react-compiler',
      {
        logger: new CustomLogger(),
      },
    ],
  ],
};

Logger Interface

interface Logger {
  // Called for each compilation event
  logEvent(filename: string | null, event: LogEvent): void;
  
  // Called for debug output (when enabled)
  debugLogIRs?(value: CompilerPipelineValue): void;
}

type LogEvent =
  | { kind: 'CompileSuccess'; fnName: string; fnLoc: SourceLocation }
  | { kind: 'CompileError'; fnName: string | null; error: CompilerError }
  | { kind: 'CompileDiagnostic'; fnName: string; diagnostic: string }
  | { kind: 'Timing'; measurement: PerformanceMeasure };

Performance Optimization

Enable Caching

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        use: {
          loader: 'babel-loader',
          options: {
            cacheDirectory: true,
            cacheCompression: false,
          },
        },
      },
    ],
  },
};

Exclude node_modules

{
  test: /\.(js|jsx)$/,
  exclude: /node_modules/,
  use: 'babel-loader',
}

Parallel Processing

Use thread-loader for parallel compilation:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/,
        use: [
          'thread-loader',
          {
            loader: 'babel-loader',
            options: {
              plugins: ['babel-plugin-react-compiler'],
              cacheDirectory: true,
            },
          },
        ],
      },
    ],
  },
};

TypeScript Support

The plugin works seamlessly with TypeScript:

babel.config.js

module.exports = {
  presets: [
    '@babel/preset-typescript',
    '@babel/preset-react',
  ],
  plugins: [
    'babel-plugin-react-compiler',
  ],
};

TSX Files

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-typescript',
              '@babel/preset-react',
            ],
            plugins: ['babel-plugin-react-compiler'],
          },
        },
      },
    ],
  },
};

Debugging

Enable Compiler Timing

ENABLE_REACT_COMPILER_TIMINGS=1 npm run build

Debug Output

Implement debugLogIRs in your logger:

class DebugLogger {
  debugLogIRs(value) {
    console.log(`[${value.kind}] ${value.name}`);
    if (value.kind === 'hir') {
      console.log(prettyPrintHIR(value.value));
    }
  }
}

Source Maps

Ensure source maps are enabled:

webpack.config.js

module.exports = {
  devtool: 'source-map',
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        use: {
          loader: 'babel-loader',
          options: {
            sourceMaps: true,
          },
        },
      },
    ],
  },
};

Troubleshooting

Plugin Order

React Compiler should run early in the plugin chain:

module.exports = {
  plugins: [
    'babel-plugin-react-compiler', // First
    '@babel/plugin-transform-runtime',
    // Other plugins...
  ],
};

Conflicting Transforms

Avoid transforms that modify React code structure:

// ✗ Bad - may conflict
plugins: [
  'babel-plugin-react-compiler',
  'some-jsx-transform', // May conflict
]

// ✓ Good
plugins: [
  'babel-plugin-react-compiler',
  // Non-React transforms
]

Memory Issues

For large codebases, increase Node memory:

package.json

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' webpack"
  }
}

Next Steps

Configuration

Detailed configuration options

ESLint Plugin

Set up React rules validation

How It Works

Understanding the compilation process

Contributing

Contribute to React Compiler

​Babel Plugin

​Installation

​Basic Setup

​Babel Configuration

​Plugin Options

​Option Structure

​Compilation Modes

​Compile All Components

​Opt-In Mode

​Opt-Out Mode

​File-Based Configuration

​Build Tool Integration

​Webpack

​Vite

​Next.js

​Create React App

​Rollup

​esbuild

​Custom Logger

​Logger Interface

​Performance Optimization

​Enable Caching

​Exclude node_modules

​Parallel Processing

​TypeScript Support

​TSX Files

​Debugging

​Enable Compiler Timing

​Debug Output

​Source Maps

​Troubleshooting

​Plugin Order

​Conflicting Transforms

​Memory Issues

​Next Steps

Configuration

ESLint Plugin

How It Works

Contributing

Babel Plugin

Installation

Basic Setup

Babel Configuration

Plugin Options

Option Structure

Compilation Modes

Compile All Components

Opt-In Mode

Opt-Out Mode

File-Based Configuration

Build Tool Integration

Webpack

Vite

Next.js

Create React App

Rollup

esbuild

Custom Logger

Logger Interface

Performance Optimization

Enable Caching

Exclude node_modules

Parallel Processing

TypeScript Support

TSX Files

Debugging

Enable Compiler Timing

Debug Output

Source Maps

Troubleshooting

Plugin Order

Conflicting Transforms

Memory Issues

Next Steps