use server

Core Idea

'use server' (feature do React) designa uma função ou arquivo para executar no servidor. No topo do arquivo, marca todas as funções exportadas como Server Functions; inline no topo de uma função, marca só aquela. Server Functions podem ser importadas em Client Components e executadas via referência que roda no servidor.

Key Concepts

• File-level vs inline: 'use server' no topo do arquivo afeta todos os exports; dentro de uma função (ex. closure num Server Component), afeta só ela.
• Server Function: função marcada com 'use server'; quando chamada de um Client Component, argumentos e retorno são serializados pela rede.
• Data Access Layer: padrão recomendado, projete funções de acesso a dado como primitivas seguras (valida input, checa auth, restringe o shape do retorno) centralizadas num único lugar.
• Autenticação por cookies/headers, não por parâmetro: leia a sessão via auth()/cookies dentro da função, nunca aceite token como argumento da função.

Code Examples

'use server'
import { db } from '@/lib/db'
import { auth } from '@/lib/auth'

export async function createUser(data: { name: string; email: string }) {
  const session = await auth()
  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  const user = await db.user.create({ data })
  return { id: user.id, name: user.name }
}

• O que demonstra: Server Function file-level com checagem de auth via session (não via parâmetro) e retorno restrito a { id, name }, nunca o registro bruto do banco.

export default async function PostPage({ params }: { params: { id: string } }) {
  const post = await getPost(params.id)

  async function updatePost(formData: FormData) {
    'use server'
    await savePost(params.id, formData)
    revalidatePath(`/posts/${params.id}`)
  }

  return <EditPost updatePostAction={updatePost} post={post} />
}

• O que demonstra: 'use server' inline dentro de uma função declarada num Server Component, passada como prop para um Client Component.

Anti-patterns

• Aceitar token/credencial como argumento da função: leia auth de cookies/headers dentro da função, não confie em parâmetro vindo do client.
• Retornar registro de banco cru: Server Function serializa e envia o retorno ao client; retorne só os campos que a UI precisa (ver Data Security guide).
• Pular validação/autorização dentro da Server Function: sem Data Access Layer centralizado, cada função vira ponto de falha de segurança independente.

Key Takeaways

1. Toda função exportada coberta por 'use server' file-level deve ser async.
2. Server Functions importadas num Client Component executam no servidor; o client recebe só uma referência, não o código.
3. Centralize validação/auth num Data Access Layer para manter a garantia de segurança em um único lugar.
4. Para comportamentos Next.js-específicos de Server Actions (modelo de resposta, config, deploy), veja o guia de Server Actions and Mutations, não esta página.

Connects To

• Directives (ch099): visão geral, incluindo onde 'use server' se encaixa.
• use client (ch103): contraparte que define a fronteira client.