Configuration

React Compiler provides extensive configuration options to customize its behavior for your project.

Basic Configuration

babel.config.js

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

Memoization Options

enablePreserveExistingMemoizationGuarantees

Type: boolean
Default: true Preserves guarantees about when values are memoized from existing useMemo/useCallback calls.

{
  enablePreserveExistingMemoizationGuarantees: true
}

When true:

Compiler uses useMemo/useCallback boundaries to understand mutation points
Guarantees existing referential equality behavior is preserved
Preserves effect execution patterns that depend on referential equality

When false:

Compiler ignores manual memoization completely
May change effect execution frequency
Mimics removing all manual memoization

validatePreserveExistingMemoizationGuarantees

Type: boolean
Default: true Validates that all useMemo/useCallback values are also memoized by the compiler.

{
  validatePreserveExistingMemoizationGuarantees: true
}

enablePreserveExistingManualUseMemo

Type: boolean
Default: false When true, keeps existing useMemo/useCallback calls instead of pruning them.

{
  enablePreserveExistingManualUseMemo: false
}

Validation Options

validateHooksUsage

Type: boolean
Default: true Validates that the component follows the Rules of Hooks.

{
  validateHooksUsage: true
}

Checks for:

Conditional hook calls
Hook calls in loops
Hook calls in nested functions

validateRefAccessDuringRender

Type: boolean
Default: true Validates that ref.current is not accessed during render.

{
  validateRefAccessDuringRender: true
}

validateNoSetStateInRender

Type: boolean
Default: true Validates that setState is not called unconditionally during render.

{
  validateNoSetStateInRender: true
}

validateNoSetStateInEffects

Type: boolean
Default: false Validates that setState is not called synchronously within effects.

{
  validateNoSetStateInEffects: false
}

validateExhaustiveMemoizationDependencies

Type: boolean
Default: true Validates that dependencies in manual memoization are exhaustive.

{
  validateExhaustiveMemoizationDependencies: true
}

validateExhaustiveEffectDependencies

Type: 'off' | 'all' | 'missing-only' | 'extra-only'
Default: 'off' Validates effect hook dependencies.

{
  validateExhaustiveEffectDependencies: 'all'
}

'off': No validation
'all': Report missing and extra dependencies
'missing-only': Only report missing dependencies
'extra-only': Only report unnecessary dependencies

validateMemoizedEffectDependencies

Type: boolean
Default: false Validates that effect dependencies are memoized to prevent infinite renders.

{
  validateMemoizedEffectDependencies: true
}

validateNoDerivedComputationsInEffects

Type: boolean
Default: false Validates that effects don’t calculate derived data that could be computed during render.

{
  validateNoDerivedComputationsInEffects: false
}

validateNoCapitalizedCalls

Type: string[] | null
Default: null Validates against calling capitalized functions (potential components with hooks).

{
  // Enable with allowlist
  validateNoCapitalizedCalls: ['Boolean', 'String', 'Number']
  
  // Enable with empty allowlist (strict)
  // validateNoCapitalizedCalls: []
}

Optimization Features

enableOptionalDependencies

Type: boolean
Default: true Infers optional chaining in dependencies.

{
  enableOptionalDependencies: true
}

// When true, infers: props?.user?.name
const name = props?.user?.name;

// When false, infers: props

lowerContextAccess

Type: boolean
Default: false Optimizes context access with selectors.

{
  lowerContextAccess: true
}

enableJsxOutlining

Type: boolean
Default: false Extracts static JSX into separate components.

{
  enableJsxOutlining: false
}

enableFunctionOutlining

Type: boolean
Default: false Outlines pure functions for better memoization.

{
  enableFunctionOutlining: false
}

Type System Options

enableUseTypeAnnotations

Type: boolean
Default: false Trusts user-supplied type annotations for better inference.

{
  enableUseTypeAnnotations: false
}

flowTypeProvider

Type: function | null
Default: null Provides Flow type information to the compiler.

{
  flowTypeProvider: (identifier) => {
    // Return Flow type information
  }
}

moduleTypeProvider

Type: function | null
Default: null Provides module type signatures for imports.

{
  moduleTypeProvider: (moduleName) => {
    // Return module type signature
    if (moduleName === 'my-library') {
      return {
        // Type information
      };
    }
    return null;
  }
}

Custom Hooks and Macros

customHooks

Type: Map<string, Hook>
Default: new Map() Defines custom hook signatures.

{
  customHooks: new Map([
    ['useMyHook', {
      effectKind: Effect.Read,
      valueKind: ValueKind.Mutable,
      noAlias: false,
      transitiveMixedData: false,
    }],
  ])
}

Hook Configuration:

interface Hook {
  // Effect of hook arguments (Read, Freeze, Store, etc.)
  effectKind: Effect;
  
  // Kind of returned value (Mutable, Frozen, Primitive)
  valueKind: ValueKind;
  
  // Whether arguments may be aliased
  noAlias: boolean;
  
  // Whether return value is transitively mixed data
  transitiveMixedData: boolean;
}

customMacros

Type: string[] | null
Default: null Lists macro function names that should not be transformed.

{
  customMacros: ['featureflag', 'css', 'graphql']
}

Development Options

enableResetCacheOnSourceFileChanges

Type: boolean | null
Default: null Enables HMR support by resetting cache when source changes.

{
  // Always enable
  enableResetCacheOnSourceFileChanges: true,
  
  // Always disable
  // enableResetCacheOnSourceFileChanges: false,
  
  // Conditional based on NODE_ENV (default)
  // enableResetCacheOnSourceFileChanges: null,
}

enableEmitFreeze

Type: ExternalFunction | null
Default: null Wraps memoized values in dev-mode mutation detector.

{
  enableEmitFreeze: {
    source: 'react-compiler-runtime',
    importSpecifierName: 'makeReadOnly',
  }
}

Generates:

import { makeReadOnly } from 'react-compiler-runtime';

function Component() {
  const $ = _c(2);
  if ($[0] !== props) {
    const value = compute(props);
    $[0] = props;
    $[1] = __DEV__ ? makeReadOnly(value) : value;
  }
}

validateSourceLocations

Type: boolean
Default: false Validates that generated AST has proper source locations.

{
  validateSourceLocations: true
}

Advanced Options

enableAssumeHooksFollowRulesOfReact

Type: boolean
Default: true Assumes hooks follow React’s rules (freeze arguments and return values).

{
  enableAssumeHooksFollowRulesOfReact: true
}

enableTransitivelyFreezeFunctionExpressions

Type: boolean
Default: true Assumes values captured by functions passed to React are not subsequently modified.

{
  enableTransitivelyFreezeFunctionExpressions: true
}

inferEffectDependencies

Type: Array<{function: ExternalFunction, autodepsIndex: number}> | null
Default: null Auto-infers and inserts effect dependencies.

{
  inferEffectDependencies: [
    {
      function: {
        source: 'react',
        importSpecifierName: 'useEffect',
      },
      autodepsIndex: 1,
    },
  ]
}

inlineJsxTransform

Type: {elementSymbol: string, globalDevVar: string} | null
Default: null Inlines JSX as object literals instead of using JSX runtime.

{
  inlineJsxTransform: {
    elementSymbol: 'react.element',
    globalDevVar: '__DEV__',
  }
}

Complete Example

babel.config.js

module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      // Memoization
      enablePreserveExistingMemoizationGuarantees: true,
      validatePreserveExistingMemoizationGuarantees: true,
      
      // Validation
      validateHooksUsage: true,
      validateRefAccessDuringRender: true,
      validateNoSetStateInRender: true,
      validateExhaustiveMemoizationDependencies: true,
      
      // Optimizations
      enableOptionalDependencies: true,
      
      // Development
      enableResetCacheOnSourceFileChanges: null, // Auto-detect
      
      // Custom hooks
      customHooks: new Map([
        ['useCustomHook', {
          effectKind: 0, // Effect.Read
          valueKind: 0,  // ValueKind.Mutable
          noAlias: false,
          transitiveMixedData: true,
        }],
      ]),
    }],
  ],
};

Environment-Specific Configuration

module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      enableResetCacheOnSourceFileChanges: true,
      validateMemoizedEffectDependencies: true,
      validateNoDerivedComputationsInEffects: true,
      enableEmitFreeze: {
        source: 'react-compiler-runtime',
        importSpecifierName: 'makeReadOnly',
      },
    }],
  ],
};

module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      enableResetCacheOnSourceFileChanges: false,
      validateMemoizedEffectDependencies: false,
      enableJsxOutlining: true,
      enableFunctionOutlining: true,
    }],
  ],
};

Next Steps

Babel Plugin

Advanced Babel integration

ESLint Plugin

Configure linting rules

How It Works

Understand compiler behavior

Architecture

Deep dive into compilation

​Configuration

​Basic Configuration

​Memoization Options

​enablePreserveExistingMemoizationGuarantees

​validatePreserveExistingMemoizationGuarantees

​enablePreserveExistingManualUseMemo

​Validation Options

​validateHooksUsage

​validateRefAccessDuringRender

​validateNoSetStateInRender

​validateNoSetStateInEffects

​validateExhaustiveMemoizationDependencies

​validateExhaustiveEffectDependencies

​validateMemoizedEffectDependencies

​validateNoDerivedComputationsInEffects

​validateNoCapitalizedCalls

​Optimization Features

​enableOptionalDependencies

​lowerContextAccess

​enableJsxOutlining

​enableFunctionOutlining

​Type System Options

​enableUseTypeAnnotations

​flowTypeProvider

​moduleTypeProvider

​Custom Hooks and Macros

​customHooks

​customMacros

​Development Options

​enableResetCacheOnSourceFileChanges

​enableEmitFreeze

​validateSourceLocations

​Advanced Options

​enableAssumeHooksFollowRulesOfReact

​enableTransitivelyFreezeFunctionExpressions

​inferEffectDependencies

​inlineJsxTransform

​Complete Example

​Environment-Specific Configuration

​Next Steps