compilationMode.md

title	compilationMode

A opção compilationMode controla como o React Compiler seleciona quais funções compilar.

{
  compilationMode: 'infer' // ou 'annotation', 'syntax', 'all'
}

---

Referência {/reference/}

compilationMode {/compilationmode/}

Controla a estratégia para determinar quais funções o React Compiler otimizará.

Tipo {/type/}

'infer' | 'syntax' | 'annotation' | 'all'

Valor padrão {/default-value/}

'infer'

Opções {/options/}

• 'infer' (padrão): O compilador usa heurísticas inteligentes para identificar componentes e hooks React:

  • Funções explicitamente anotadas com a diretiva "use memo"
  • Funções que têm nomes como componentes (PascalCase) ou hooks (use prefixo) E criam JSX e/ou chamam outros hooks

• 'annotation': Compila apenas funções explicitamente marcadas com a diretiva "use memo". Ideal para adoção incremental.

• 'syntax': Compila apenas componentes e hooks que usam a sintaxe de componente e hook do Flow.

• 'all': Compila todas as funções de nível superior. Não recomendado, pois pode compilar funções não-React.

Ressalvas {/caveats/}

• O modo 'infer' exige que as funções sigam as convenções de nomenclatura do React para serem detectadas
• Usar o modo 'all' pode impactar negativamente o desempenho ao compilar funções utilitárias
• O modo 'syntax' requer Flow e não funcionará com TypeScript
• Independentemente do modo, funções com a diretiva "use no memo" são sempre ignoradas

---

Uso {/usage/}

Modo de inferência padrão {/default-inference-mode/}

O modo padrão 'infer' funciona bem para a maioria das bases de código que seguem as convenções do React:

{
  compilationMode: 'infer'
}

Com este modo, estas funções serão compiladas:

// ✅ Compilado: Nomeado como um componente + retorna JSX
function Button(props) {
  return <button>{props.label}</button>;
}

// ✅ Compilado: Nomeado como um hook + chama hooks
function useCounter() {
  const [count, setCount] = useState(0);
  return [count, setCount];
}

// ✅ Compilado: Diretiva explícita
function expensiveCalculation(data) {
  "use memo";
  return data.reduce(/* ... */);
}

// ❌ Não compilado: Não é um padrão de componente/hook
function calculateTotal(items) {
  return items.reduce((a, b) => a + b, 0);
}

Adoção incremental com modo de anotação {/incremental-adoption/}

Para migração gradual, use o modo 'annotation' para compilar apenas funções marcadas:

{
  compilationMode: 'annotation'
}

Em seguida, marque explicitamente as funções para compilar:

// Apenas esta função será compilada
function ExpensiveList(props) {
  "use memo";
  return (
    <ul>
      {props.items.map(item => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

// Isso não será compilado sem a diretiva
function NormalComponent(props) {
  return <div>{props.content}</div>;
}

Usando o modo de sintaxe Flow {/flow-syntax-mode/}

Se sua base de código usa Flow em vez de TypeScript:

{
  compilationMode: 'syntax'
}

Em seguida, use a sintaxe de componente do Flow:

// Compilado: Sintaxe de componente Flow
component Button(label: string) {
  return <button>{label}</button>;
}

// Compilado: Sintaxe de hook Flow
hook useCounter(initial: number) {
  const [count, setCount] = useState(initial);
  return [count, setCount];
}

// Não compilado: Sintaxe de função regular
function helper(data) {
  return process(data);
}

Desativando funções específicas {/opting-out/}

Independentemente do modo de compilação, use "use no memo" para pular a compilação:

function ComponentWithSideEffects() {
  "use no memo"; // Previne a compilação

  // Este componente tem efeitos colaterais que não devem ser memorizados
  logToAnalytics('component_rendered');

  return <div>Content</div>;
}

---

Solução de problemas {/troubleshooting/}

Componente não está sendo compilado no modo infer {/component-not-compiled-infer/}

No modo 'infer', certifique-se de que seu componente siga as convenções do React:

// ❌ Não será compilado: nome em minúsculas
function button(props) {
  return <button>{props.label}</button>;
}

// ✅ Será compilado: nome em PascalCase
function Button(props) {
  return <button>{props.label}</button>;
}

// ❌ Não será compilado: não cria JSX ou chama hooks
function useData() {
  return window.localStorage.getItem('data');
}

// ✅ Será compilado: chama um hook
function useData() {
  const [data] = useState(() => window.localStorage.getItem('data'));
  return data;
}