Directives

Core Idea

Directives são literais string que instruem o compilador/bundler sobre como tratar o código ao redor: criam um entry point de client, expõem Server Functions, ou fazem cache de output. Página de visão geral que explica onde colocar cada uma e o que cada uma exige.

Key Concepts

• 'use client': definido pelo React, cria entry point de client a partir de Server Components; obrigatório no topo do arquivo, antes de imports, aplica-se ao módulo inteiro.
• 'use server': definido pelo React, expõe funções server-side como Server Functions; toda função exportada coberta deve ser async.
• 'use cache': definido pelo Next.js, cacheia e reusa output baseado nos inputs da função; tem variantes 'use cache: remote' e 'use cache: private'.
• Escopo de aplicação: 'use server'/'use cache' no topo do arquivo aplicam a todo export; dentro de uma função, aplicam só a ela.

Code Examples

// File-level: applies to every export
'use cache'

export async function getUser(id: string) {
  return { id }
}

// Function-level: applies to this function only
export async function User() {
  'use cache'
  return <p>User</p>
}

• O que demonstra: diferença entre directive em nível de arquivo (afeta todos os exports) e em nível de função (afeta só aquela função/componente).

Reference Tables

Directive	Defined by	Effect
'use client'	React	Creates a client entry point from Server Components
'use server'	React	Exposes server-side functions as Server Functions
'use cache'	Next.js	Caches and reuses output based on the code's inputs

Anti-patterns

• Directive inline em 'use client': não existe, 'use client' só funciona no topo do arquivo, aplicando-se ao módulo inteiro.
• Declarar 'use server'/'use cache' em módulo 'use client': sempre declare em módulos server; para chamar de um Client Component, exporte a função de um módulo server e importe a referência.
• Função exportada não-async sob directive de arquivo: toda função coberta por 'use server'/'use cache' em nível de arquivo precisa ser async, incluindo generateMetadata/generateStaticParams quando 'use cache' está no topo de page/layout.

Key Takeaways

1. 'use client' é sempre file-level; 'use server'/'use cache' podem ser file-level ou function-level.
2. Placement de 'use cache' decide o escopo do cache: no topo da page cacheia página + componentes importados; dentro de uma função de dados, cacheia só aquele resultado.
3. Props de Client Component que cruzam a fronteira 'use client' devem ser serializáveis; funções comuns não cruzam, Server Functions cruzam como referência.
4. Código coberto por 'use cache' não pode ler cookies(), headers() ou searchParams diretamente.

Connects To

• use cache (ch100): detalhamento completo da directive de cache.
• use client (ch103) e use server (ch104): detalhamento das outras duas directives.
• use cache: remote (ch102) e use cache: private (ch101): variantes de 'use cache'.