Directives

React Compiler directives are special string literals that control whether specific functions are compiled.

function MyComponent() {
  "use memo"; // Opt this component into compilation
  return <div>{/* ... */}</div>;
}

Overview
- Available directives
- Quick comparison
Usage
Best practices
Common patterns
- Gradual adoption
Troubleshooting
- Common issues
See also

Overview

React Compiler directives provide fine-grained control over which functions are optimized by the compiler. They are string literals placed at the beginning of a function body or at the top of a module.

Available directives

"use memo" - Opts a function into compilation
"use nemo" - Blocks Hooks inside the function
"use no memo" - Opts a function out of compilation

Quick comparison

Directive	Purpose	When to use
`"use memo"`	Force compilation	When using `annotation` mode or to override `infer` mode heuristics
`"use nemo"`	Forbid Hooks	Enforcing hook-free components or critical render paths
`"use no memo"`	Prevent compilation	Debugging issues or working with incompatible code

Usage

Function-level directives

Place directives at the beginning of a function to control its compilation:

// Opt into compilation
function OptimizedComponent() {
  "use memo";
  return <div>This will be optimized</div>;
}

// Opt out of compilation
function UnoptimizedComponent() {
  "use no memo";
  return <div>This won't be optimized</div>;
}

Module-level directives

Place directives at the top of a file to affect all functions in that module:

// At the very top of the file
"use memo";

// All functions in this file will be compiled
function Component1() {
  return <div>Compiled</div>;
}

function Component2() {
  return <div>Also compiled</div>;
}

// Can be overridden at function level
function Component3() {
  "use no memo"; // This overrides the module directive
  return <div>Not compiled</div>;
}

Compilation modes interaction

Directives behave differently depending on your compilationMode:

annotation mode: Only functions with "use memo" are compiled
infer mode: Compiler decides what to compile, directives override decisions
all mode: Everything is compiled, "use no memo" can exclude specific functions

Best practices

Use directives sparingly

Directives are escape hatches. Prefer configuring the compiler at the project level:

// ✅ Good - project-wide configuration
{
  plugins: [
    ['babel-plugin-react-compiler', {
      compilationMode: 'infer'
    }]
  ]
}

// ⚠️ Use directives only when needed
function SpecialCase() {
  "use no memo"; // Document why this is needed
  // ...
}

Document directive usage

Always explain why a directive is used:

// ✅ Good - clear explanation
function DataGrid() {
  "use no memo"; // TODO: Remove after fixing issue with dynamic row heights (JIRA-123)
  // Complex grid implementation
}

// ❌ Bad - no explanation
function Mystery() {
  "use no memo";
  // ...
}

Plan for removal

Opt-out directives should be temporary:

Add the directive with a TODO comment
Create a tracking issue
Fix the underlying problem
Remove the directive

function TemporaryWorkaround() {
  "use no memo"; // TODO: Remove after upgrading ThirdPartyLib to v2.0
  return <ThirdPartyComponent />;
}

Common patterns

Gradual adoption

When adopting the React Compiler in a large codebase:

// Start with annotation mode
{
  compilationMode: 'annotation'
}

// Opt in stable components
function StableComponent() {
  "use memo";
  // Well-tested component
}

// Later, switch to infer mode and opt out problematic ones
function ProblematicComponent() {
  "use no memo"; // Fix issues before removing
  // ...
}

Troubleshooting

For specific issues with directives, see the troubleshooting sections in:

Common issues

Directive ignored: Check placement (must be first) and spelling
Compilation still happens: Check ignoreUseNoForget setting
Module directive not working: Ensure it’s before all imports