Pular para o conteúdo
Documentação do Next.js PT-BR

Server e Client Components

Por padrão, layouts e páginas são Server Components, o que permite buscar dados e renderizar partes da sua UI no servidor, opcionalmente colocar o resultado em cache e fazer streaming dele para o cliente. Quando você precisa de interatividade ou de APIs do navegador, pode usar Client Components para adicionar funcionalidades.

Esta página explica como Server e Client Components funcionam no Next.js e quando usá-los, com exemplos de como combiná-los no seu app.

Bom saber: para uma explicação de onde cada tipo de componente roda e de como funciona a fronteira entre eles, veja A fronteira entre Server e Client.

Quando usar Server e Client Components?

Os ambientes do cliente e do servidor têm capacidades diferentes. Server e Client Components permitem executar lógica em cada ambiente, dependendo do seu caso de uso.

Use Client Components quando precisar de:

Use Server Components quando precisar de:

  • Buscar dados de bancos de dados ou APIs próximos da fonte.
  • Usar chaves de API, tokens e outros segredos sem expô-los ao cliente.
  • Reduzir a quantidade de JavaScript enviada ao navegador.
  • Melhorar o First Contentful Paint (FCP) e transmitir o conteúdo progressivamente ao cliente.

Por exemplo, o componente <Page> é um Server Component que busca dados sobre um post e os passa como props para o <LikeButton>, que cuida da interatividade no cliente.

app/[id]/page.tsx
import LikeButton from '@/app/ui/like-button'
import { getPost } from '@/lib/data'

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const post = await getPost(id)

  return (
    <div>
      <main>
        <h1>{post.title}</h1>
        {/* ... */}
        <LikeButton likes={post.likes} />
      </main>
    </div>
  )
}
app/ui/like-button.tsx
'use client'

import { useState } from 'react'

export default function LikeButton({ likes }: { likes: number }) {
  // ...
}

Como Server e Client Components funcionam no Next.js?

No servidor

No servidor, o Next.js usa as APIs do React para orquestrar a renderização. O trabalho de renderização é dividido em partes, por segmento de rota individual (layouts e páginas), incluindo slots de rotas paralelas, estejam eles exibidos ou não:

  • Server Components são renderizados em um formato de dados especial chamado React Server Component Payload (RSC Payload).
  • Client Components e o RSC Payload são usados para fazer o prerendering do HTML.

O que é o React Server Component Payload (RSC)?

O RSC Payload é uma representação serializada e compacta da árvore de React Server Components renderizada. O React a usa no cliente para atualizar o DOM do navegador. O RSC Payload contém:

  • O resultado renderizado dos Server Components
  • Placeholders indicando onde os Client Components devem ser renderizados e referências aos seus arquivos JavaScript
  • Quaisquer props passadas de um Server Component para um Client Component

No cliente (primeiro carregamento)

Em seguida, no cliente:

  1. HTML é usado para mostrar imediatamente uma prévia rápida e não interativa da rota ao usuário.
  2. RSC Payload é usado para reconciliar as árvores de Client e Server Components.
  3. JavaScript é usado para fazer a hydration dos Client Components e tornar o app interativo.

O que é hydration?

Hydration é o processo do React para anexar manipuladores de eventos ao DOM, tornando o HTML estático interativo.

Navegações seguintes

Nas navegações seguintes:

  • É feito o prefetch do RSC Payload, que fica armazenado em cache para uma navegação instantânea.
  • Client Components são renderizados inteiramente no cliente, sem o HTML renderizado no servidor.

Exemplos

Usando Client Components

Você pode criar um Client Component adicionando a diretiva "use client" no topo do arquivo, acima dos imports.

app/ui/counter.tsx
'use client'

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>{count} likes</p>
      <button onClick={() => setCount(count + 1)}>Click me</button>
    </div>
  )
}

"use client" é usado para declarar uma fronteira entre os grafos de módulos (árvores) do Server e do Client.

Depois que um arquivo é marcado com "use client", todos os seus imports e os componentes que ele renderiza diretamente são incluídos no bundle do cliente. Isso significa que você não precisa adicionar a diretiva em todo componente destinado ao cliente.

Esse comportamento se aplica aos componentes que fazem parte do grafo de módulos de um Client Component, que inclui os módulos que ele importa e os componentes que ele renderiza diretamente. Não se aplica a Server Components passados como children ou outras props. Esses componentes não são importados para o grafo de módulos do Client Component. Eles são renderizados no servidor e passados ao Client Component como saída já renderizada.

Veja Intercalando Server e Client Components para saber como Server e Client Components podem ser combinados.

Reduzindo o tamanho do bundle JS

Para reduzir o tamanho dos bundles JavaScript do cliente, adicione 'use client' no topo dos arquivos que definem seus componentes interativos, em vez de marcar grandes partes da UI como Client Components.

Por exemplo, o componente <Layout> contém principalmente elementos estáticos, como um logo e links de navegação, mas inclui uma barra de busca interativa. <Search /> precisa ser um Client Component, enquanto o restante do layout pode continuar sendo um Server Component.

app/layout.tsx
// Client Component
import Search from './search'
// Server Component
import Logo from './logo'

// Layout is a Server Component by default
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <nav>
        <Logo />
        <Search />
      </nav>
      <main>{children}</main>
    </>
  )
}
app/ui/search.tsx
'use client'

export default function Search() {
  // ...
}

Passando dados do Server para Client Components

Você pode passar dados de Server Components para Client Components usando props.

app/[id]/page.tsx
import LikeButton from '@/app/ui/like-button'
import { getPost } from '@/lib/data'

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const post = await getPost(id)

  return <LikeButton likes={post.likes} />
}
app/ui/like-button.tsx
'use client'

export default function LikeButton({ likes }: { likes: number }) {
  // ...
}

Alternativamente, você pode transmitir dados de um Server Component para um Client Component com a API use. Veja um exemplo.

Bom saber: props passadas para Client Components precisam ser serializáveis pelo React.

Intercalando Server e Client Components

Você pode passar Server Components como prop para um Client Component. Isso permite aninhar visualmente UI renderizada no servidor dentro de Client Components.

Um padrão comum é usar children para criar um slot em um <ClientComponent>. Por exemplo, um componente <Cart> que busca dados no servidor, dentro de um componente <Modal> que usa estado do cliente para alternar a visibilidade.

app/ui/modal.tsx
'use client'

export default function Modal({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
}

Depois, em um Server Component pai (por exemplo, <Page>), você pode passar um <Cart> como filho do <Modal>:

app/page.tsx
import Modal from './ui/modal'
import Cart from './ui/cart'

export default function Page() {
  return (
    <Modal>
      <Cart />
    </Modal>
  )
}

Nesse padrão, Server Components são renderizados no servidor antecipadamente, mesmo quando passados como props para Client Components. O React Server Component Payload contém o resultado renderizado desses Server Components, além de placeholders indicando onde os Client Components devem ser renderizados e referências aos seus arquivos JavaScript.

Providers de context

Context do React é comumente usado para compartilhar estado global, como o tema atual. No entanto, o context do React não tem suporte em Server Components.

Para usar context, crie um Client Component que aceite children:

app/theme-provider.tsx
'use client'

import { createContext } from 'react'

export const ThemeContext = createContext({})

export default function ThemeProvider({
  children,
}: {
  children: React.ReactNode
}) {
  return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider>
}

Depois, importe-o em um Server Component (por exemplo, layout):

app/layout.tsx
import ThemeProvider from './theme-provider'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

Seu Server Component agora poderá renderizar o provider diretamente, e todos os outros Client Components do seu app poderão consumir esse context.

Bom saber: renderize providers o mais fundo possível na árvore. Repare que ThemeProvider envolve apenas {children}, em vez de todo o documento <html>. Isso facilita para o Next.js otimizar as partes estáticas dos seus Server Components.

Para passar dados buscados no servidor por meio de context e lê-los em Client Components com use(), veja Usando o use do React dentro de um Context Provider.

Componentes de terceiros

Ao usar um componente de terceiros que depende de recursos exclusivos do cliente, você pode envolvê-lo em um Client Component para garantir que ele funcione como esperado.

Por exemplo, o <Carousel /> pode ser importado do pacote acme-carousel. Esse componente usa useState, mas o módulo que o define ainda não tem a diretiva "use client".

Se você usar <Carousel /> dentro de um Client Component, ele funcionará como esperado:

app/gallery.tsx
'use client'

import { useState } from 'react'
import { Carousel } from 'acme-carousel'

export default function Gallery() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>View pictures</button>
      {/* Works, since Carousel is used within a Client Component */}
      {isOpen && <Carousel />}
    </div>
  )
}

No entanto, se você tentar usá-lo diretamente dentro de um Server Component, verá um erro. Isso acontece porque o Next.js não sabe que o <Carousel /> usa recursos exclusivos do cliente.

Para resolver, envolva os componentes de terceiros que dependem de recursos exclusivos do cliente em seus próprios Client Components:

app/carousel.tsx
'use client'

import { Carousel } from 'acme-carousel'

export default Carousel

Agora você pode usar <Carousel /> diretamente dentro de um Server Component:

app/page.tsx
import Carousel from './carousel'

export default function Page() {
  return (
    <div>
      <p>View pictures</p>
      {/*  Works, since Carousel is a Client Component */}
      <Carousel />
    </div>
  )
}

Recomendação para autores de bibliotecas

Se você estiver criando uma biblioteca de componentes, adicione a diretiva "use client" nos entry points que dependem de recursos exclusivos do cliente. Assim, seus usuários podem importar os componentes em Server Components sem precisar criar wrappers.

Vale notar que alguns bundlers podem remover as diretivas "use client". Você pode encontrar um exemplo de como configurar o esbuild para incluir a diretiva "use client" nos repositórios do React Wrap Balancer e do Vercel Analytics.

Evitando contaminação de ambiente

Módulos JavaScript podem ser compartilhados entre os módulos de Server e de Client Components. Isso significa que é possível importar acidentalmente código exclusivo do servidor no cliente. Por exemplo, considere a seguinte função:

lib/data.ts
export async function getData() {
  const res = await fetch('https://external-service.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  })

  return res.json()
}

Essa função contém uma API_KEY que nunca deve ser exposta ao cliente.

No Next.js, apenas variáveis de ambiente com o prefixo NEXT_PUBLIC_ são incluídas no bundle do cliente. Se as variáveis não tiverem esse prefixo, o Next.js as substitui por uma string vazia.

Como resultado, mesmo que getData() possa ser importada e executada no cliente, ela não funcionará como esperado.

Para evitar o uso acidental em Client Components, você pode usar o pacote server-only.

Depois, importe o pacote em um arquivo que contém código exclusivo do servidor:

lib/data.js
import 'server-only'

export async function getData() {
  const res = await fetch('https://external-service.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  })

  return res.json()
}

Agora, se você tentar importar o módulo em um Client Component, haverá um erro em tempo de build.

O pacote client-only correspondente pode ser usado para marcar módulos que contêm lógica exclusiva do cliente, como código que acessa o objeto window.

No Next.js, instalar server-only ou client-only é opcional. No entanto, se suas regras de lint apontarem dependências extras, você pode instalá-los para evitar problemas.

npm install server-only

O Next.js trata os imports de server-only e client-only internamente para fornecer mensagens de erro mais claras quando um módulo é usado no ambiente errado. O conteúdo desses pacotes do NPM não é usado pelo Next.js.

O Next.js também fornece suas próprias declarações de tipo para server-only e client-only, para configurações de TypeScript em que noUncheckedSideEffectImports está ativo.

Próximos passos

Saiba mais sobre as APIs mencionadas nesta página.