Capítulo 171 de 456

root-params

Core Idea

O módulo next/root-params expõe getters async para ler parâmetros de segmentos dinâmicos que ficam ACIMA do root layout, acessíveis de qualquer Server Component sem prop drilling.

Key Concepts

  • Root parameter: segmento dinâmico que aparece no caminho até o root layout (ex.: app/[lang]/layout.tsx → lang é root param). Segmentos abaixo do root layout são acessados via prop params normal.
  • Getter gerado por nome de pasta: app/[locale] gera export locale de next/root-params.
  • Restrição de identificador: nomes com kebab-case ([post-slug]) não são suportados, causam erro em dev/build.
  • Server Components only: não pode ser usado em Client Components, Server Actions, ou Route Handlers (suporte a Route Handlers está planejado).
  • Não funciona em unstable_cache: lança erro em runtime; use use cache no lugar.
  • Cache key otimizado: dentro de função com 'use cache', só os root params efetivamente usados entram na cache key, não todos os segmentos dinâmicos da rota.
  • Múltiplos root layouts: se um parâmetro não existe em todos os root layouts, o tipo de retorno inclui undefined.

Code Examples

// app/[lang]/layout.tsx
import { lang } from 'next/root-params'

export default async function RootLayout(props: LayoutProps<'/[lang]'>) {
  return (
    <html lang={await lang()}>
      <body>{props.children}</body>
    </html>
  )
}
  • O que demonstra: leitura de root param lang direto no root layout, sem passar via props.
// Uso em utilitário compartilhado, sem prop drilling
import { lang } from 'next/root-params'

export async function getTranslations() {
  const language = await lang()
  return import(`@/locales/${language}.json`)
}
  • O que demonstra: acessar root param em código server-side arbitrário (fora de page/layout).
// generateStaticParams com Cache Components — cada root param precisa de ao menos um valor
export async function generateStaticParams() {
  return [{ lang: 'en' }, { lang: 'fr' }]
}
  • O que demonstra: obrigatório fornecer valores quando Cache Components está ativo.

Reference Tables

Segment typeExampleReturn type
Dynamic[id]string
Catch-all[...path]string[]
Optional catch-all[[...path]]string[] | undefined
VersionChanges
v16.3.0next/root-params introduzido

Anti-patterns

  • Usar em Client Component: build error — next/root-params só funciona em Server Components.
  • Usar dentro de unstable_cache: erro em runtime; migre para use cache.
  • Usar em Server Actions: erro; root params não estão disponíveis nesse contexto.
  • Nome de segmento kebab-case: [post-slug] não vira identificador JS válido, evite.

Key Takeaways

  1. Root params evitam prop drilling de valores como locale/lang por toda a árvore de componentes.
  2. Só segmentos ACIMA do root layout viram root params; abaixo disso, use a prop params normal.
  3. Com múltiplos root layouts, o tipo de retorno pode incluir undefined — trate esse caso.
  4. Otimiza cache key de funções 'use cache', evitando invalidação por segmentos não utilizados.

Connects To

  • generateStaticParams: precisa fornecer valores para cada root param quando Cache Components está ativo.
  • use cache: única forma de cachear leitura de root params (não funciona com unstable_cache).
  • layout.js (root layout): onde os root params são definidos estruturalmente.
AnteriorNextResponsePróximonotFound