Incremental Adoption

Why Incremental Adoption?

While React Compiler is designed to handle most React code automatically, adopting it incrementally allows you to:

• Test the compiler on a small portion of your app first
• Identify and fix any Rules of React violations
• Build confidence before expanding to your entire codebase
• Minimize risk in production applications

Approaches to Incremental Adoption

There are three main approaches to adopt React Compiler incrementally:

1. Babel overrides - Apply the compiler to specific directories
2. Opt-in with “use memo” - Only compile components that explicitly opt in
3. Runtime gating - Control compilation with feature flags

All approaches allow you to test the compiler on specific parts of your application before full rollout.

Directory-Based Adoption with Babel Overrides

Babel’s overrides option lets you apply different plugins to different parts of your codebase. This is ideal for gradually adopting React Compiler directory by directory.

Basic Configuration

Start by applying the compiler to a specific directory:

// babel.config.js
module.exports = {
  plugins: [
    // Global plugins that apply to all files
  ],
  overrides: [
    {
      test: './src/modern/**/*.{js,jsx,ts,tsx}',
      plugins: [
        'babel-plugin-react-compiler'
      ]
    }
  ]
};

Expanding Coverage

As you gain confidence, add more directories:

// babel.config.js
module.exports = {
  plugins: [
    // Global plugins
  ],
  overrides: [
    {
      test: ['./src/modern/**/*.{js,jsx,ts,tsx}', './src/features/**/*.{js,jsx,ts,tsx}'],
      plugins: [
        'babel-plugin-react-compiler'
      ]
    },
    {
      test: './src/legacy/**/*.{js,jsx,ts,tsx}',
      plugins: [
        // Different plugins for legacy code
      ]
    }
  ]
};

With Compiler Options

You can also configure compiler options per override:

// babel.config.js
module.exports = {
  plugins: [],
  overrides: [
    {
      test: './src/experimental/**/*.{js,jsx,ts,tsx}',
      plugins: [
        ['babel-plugin-react-compiler', {
          compilationMode: 'annotation', // Only compile "use memo" components
          panicThreshold: 'NONE' // More permissive for experimental code
        }]
      ]
    },
    {
      test: './src/production/**/*.{js,jsx,ts,tsx}',
      plugins: [
        ['babel-plugin-react-compiler', {
          panicThreshold: 'CRITICAL_ERRORS' // Stricter for production code
        }]
      ]
    }
  ]
};

Opt-in Mode with “use memo”

For maximum control, you can use compilationMode: 'annotation' to only compile components and hooks that explicitly opt in with the "use memo" directive.

Annotation Mode Configuration

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      compilationMode: 'annotation',
    }],
  ],
};

Using the Directive

Add "use memo" at the beginning of functions you want to compile:

function TodoList({ todos }) {
  "use memo"; // Opt this component into compilation

  const sortedTodos = todos.slice().sort();

  return (
    <ul>
      {sortedTodos.map(todo => (
        <TodoItem key={todo.id} todo={todo} />
      ))}
    </ul>
  );
}

function useSortedData(data) {
  "use memo"; // Opt this hook into compilation

  return data.slice().sort();
}

With compilationMode: 'annotation', you must:

• Add "use memo" to every component you want optimized
• Add "use memo" to every custom hook
• Remember to add it to new components

This gives you precise control over which components are compiled while you evaluate the compiler’s impact.

Runtime Feature Flags with Gating

The gating option enables you to control compilation at runtime using feature flags. This is useful for running A/B tests or gradually rolling out the compiler based on user segments.

How Gating Works

The compiler wraps optimized code in a runtime check. If the gate returns true, the optimized version runs. Otherwise, the original code runs.

Gating Configuration

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      gating: {
        source: 'ReactCompilerFeatureFlags',
        importSpecifierName: 'isCompilerEnabled',
      },
    }],
  ],
};

Implementing the Feature Flag

Create a module that exports your gating function:

// ReactCompilerFeatureFlags.js
export function isCompilerEnabled() {
  // Use your feature flag system
  return getFeatureFlag('react-compiler-enabled');
}

Troubleshooting Adoption

If you encounter issues during adoption:

1. Use "use no memo" to temporarily exclude problematic components
2. Check the debugging guide for common issues
3. Fix Rules of React violations identified by the ESLint plugin
4. Consider using compilationMode: 'annotation' for more gradual adoption

Next Steps

• Read the configuration guide for more options
• Learn about debugging techniques
• Check the API reference for all compiler options