Next.js em produção

Use para qualquer código em um app Next.js 16 App Router. Regras específicas de segurança (auth em actions, CSP, headers, taint) estão em nextjs-security; regras de container em docker-nextjs. A skill integrada next-best-practices do Claude Code cobre convenções gerais de arquivos, metadados, otimização de imagens e fontes em profundidade; esta skill adiciona apenas o que é específico para como construímos e entregamos.

Linha de base: Next 16.4, React 19.3, Turbopack (padrão para dev e build), cacheComponents: true com partialPrefetching: true, output: "standalone", typedRoutes: true. O next.config.ts do template é a fonte da verdade.

Regras

Componentes Servidor por padrão; "use client" apenas para estado, efeitos, APIs de navegador ou manipuladores de eventos. Coloque a diretiva na menor folha que precisar dela. Não a adicione porque um arquivo importa nuvui: as partes stateful do nuvui carregam sua própria diretiva (veja a skill nuvui, rules/server-components.md).
```
// Errado: página inteira é cliente por causa de um manipulador
"use client";
export default function Page() { … <Select onValueChange={…} /> … }

// Certo: a página permanece no servidor, o manipulador vive em uma folha
export default async function Page() {
  const people = await getPeople();
  return <PeopleFilter people={people} />; // people-filter.tsx tem "use client"
}
```
Props que cruzam para um componente cliente devem ser serializáveis: sem funções (exceto Server Actions), sem instâncias de classe.
Faça fetch no servidor, no componente que precisa dos dados. Sem fetch com useEffect, sem route handler apenas para alimentar sua própria página. Desduplique por requisição com cache() do React; armazene em cache entre requisições com a regra 3.
Cache com "use cache" + cacheLife + cacheTag; todo o resto é dinâmico. Com Cache Components, nada é armazenado em cache a menos que você diga, e fetch não tem cache implícito.
```
import { cacheLife, cacheTag } from "next/cache";

export async function getInvoice(id: InvoiceId) {
  "use cache";
  cacheLife("minutes");
  cacheTag(`invoice:${id}`);
  return db.invoice.findUnique({ where: { id } });
}
```
Não use a configuração antiga de segmento (export const dynamic, revalidate, fetchCache): ela gera erro sob Cache Components. Argumentos e valores fechados se tornam parte da chave de cache, então passe ids, não objetos de requisição inteiros. Detalhes, os perfis e "use cache: private": references/caching.md.
Invalide com updateTag em Server Actions, revalidateTag(tag, "max") em outros lugares. updateTag(tag) proporciona consistência de leitura-após-escrita e funciona apenas dentro de uma Server Action. De um webhook ou route handler use revalidateTag(tag, "max") (stale-while-revalidate) ou revalidateTag(tag, { expire: 0 }). A versão com um argumento revalidateTag(tag) está obsoleta.
Empacote dados em tempo de requisição dentro de <Suspense>, ou a build falha. cookies(), headers(), searchParams, connection() e I/O não armazenado em cache fora de um limite Suspense interrompem o pré-renderização com "dados não armazenados em cache ou em tempo de execução durante pré-renderização". Dê a ele um limite com um fallback skeleton, armazene em cache, ou (apenas layout raiz, veja regra 14) marque a rota como bloqueante com export const instant = false. Todos params, searchParams, cookies(), headers() são assíncronos: use await neles.

Toda Server Action valida sua entrada e verifica autorização por conta própria. Uma Server Action é um endpoint POST público independentemente da página em que está escrita. Analise FormData com o schema de typescript-production (valibot), depois autorize, depois mutação, depois updateTag. Retorne um resultado tipado para falhas esperadas; lance apenas para bugs. O conjunto completo de regras está em nextjs-security.

"use server";
export async function renameProject(_: State, form: FormData): Promise<State> {
  const session = await requireSession();                  // 401 se ausente
  const input = v.safeParse(RenameProject, Object.fromEntries(form));
  if (!input.success) return { ok: false, errors: flatten(input.issues) };
  await assertCanEdit(session, input.output.projectId);    // 403 se não autorizado
  await db.project.update(…);
  updateTag(`project:${input.output.projectId}`);
  return { ok: true };
}

Route handlers são para outros clientes (webhooks, mobile, health), não para suas próprias páginas. Coloque-os em app/api/. Valide o corpo como uma ação, retorne Response.json(...) e defina códigos de status intencionalmente.
Todo app tem GET /api/health, dinâmico e sem dependências. O HEALTHCHECK do Docker e as probes do Kubernetes o acessam. Deve responder sem tocar no banco de dados, para que uma dependência lenta não reinicie todos os pods. await connection() impede que seja pré-renderizado em um arquivo estático. Está no template em src/app/api/health/route.ts; proxy.ts exclui /api/health do seu matcher.
error.tsx, loading.tsx e not-found.tsx na raiz, e por segmento onde a UX difere. error.tsx é um componente cliente; registre através de onRequestError em instrumentation.ts, mostre uma tentativa com reset, nunca a mensagem de erro. Chame notFound() para registros ausentes em vez de renderizar um estado vazio.
NEXT_PUBLIC_* é incorporado na build; todo o resto é lido em tempo de execução no servidor. Uma imagem é promovida de main para produção inalterada, então um valor NEXT_PUBLIC_ é o mesmo em todos os ambientes. Coloque apenas constantes de build lá (nome do app, um Sentry DSN público que é o mesmo em todos os lugares). Configuração por ambiente (URLs de API, feature flags, segredos) é um process.env.X no lado do servidor, lido em um Componente Servidor ou ação, e passado para o cliente como props se necessário. Valide env uma vez em src/env.ts (valibot) e importe de lá. Nunca use a chave env em next.config.ts: ela é inlinada em bundles do cliente.
Marque módulos apenas do servidor com import "server-only". Qualquer coisa que leia segredos, converse com o BD ou importe um SDK com credenciais. Uma importação cliente disso falha na build em vez de vazar.
after() para trabalho que não deve atrasar a resposta (logs de auditoria, análises, aquecimento de cache). Leia cookies()/headers() antes de chamar after, não dentro dele. Ele executa no mesmo processo, então o pod precisa de seu período de graça SIGTERM (o chart define terminationGracePeriodSeconds).
Instrumente com src/instrumentation.ts: registerOTel + onRequestError. OpenTelemetry via @vercel/otel, exportador configurado pelas variáveis de ambiente padrão OTEL_EXPORTER_OTLP_* em tempo de execução. Veja references/observability.md.
Mantenha output: "standalone" e nunca importe de fora do workspace. O runner Docker copia apenas .next/standalone, .next/static e public. No monorepo, server.js está em .next/standalone/apps/<app>/server.js; a raiz do workspace é encontrada a partir de pnpm-lock.yaml, então não defina outputFileTracingRoot ou turbopack.root a menos que a build avise. Detalhes de self-hosting (multi-replica, chaves Server Action, deploymentId): references/self-hosting.md.
O layout raiz lê o nonce CSP, então o app renderiza por requisição. O proxy.ts do template define um CSP baseado em nonce e src/app/layout.tsx tem export const instant = false. Isso é uma troca deliberada: nonces e shells estáticos pré-renderizados não podem coexistir, e para apps de negócios logados um CSP estrito vence. O cache de dados com "use cache" ainda funciona. Não remova nenhuma das partes sem ler a regra 4 de nextjs-security.
Estilos: SCSS BEM global, importado pelo componente. Turbopack compila Sass com o pacote sass; sassOptions.loadPaths: ["src/styles"] faz @use "abstracts" funcionar de qualquer profundidade. Sem imports ~, sem sassOptions.functions. Regras em scss-bem.
Imagens através de next/image, fontes através de next/font. sharp vem com Next para o otimizador; a imagem do runner não precisa de pacote extra. Imagens remotas precisam de images.remotePatterns com um hostname exato.
Verifique o tamanho do bundle com pnpm next analyze (analisador do Turbopack; @next/bundle-analyzer é apenas webpack). Carregue componentes cliente pesados (editor nuvui, mapas, gráficos abaixo da dobra) com next/dynamic.
Use rotas tipadas e tipos gerados. typedRoutes: true verifica <Link href>; PageProps<"/invoices/[id]"> e LayoutProps são globais após next typegen (executado automaticamente por next dev/next build). Não escreva tipos params manualmente.
Sem next lint. Foi removido na versão 16. Biome faz lint (veja biome); TypeScript verifica com tsc --noEmit por pacote.

Verificar

pnpm typecheck
pnpm lint
pnpm build                      # turbo run build: falha em erros de pré-renderização, erros de tipo, erros Sass
pnpm --filter <app> start &     # então:
curl -fsS localhost:3000/api/health

Nuvraxis/nuvraxis-plugins

O que é nuvraxis-plugins?

Perguntar na sua IA favorita

Documentação

Next.js em produção

Regras

Verificar

Fontes

Individual skills in this repo