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

Busca de dados

Esta página mostra como buscar dados em Server e Client Components, e como fazer streaming de componentes que dependem de dados não armazenados em cache.

Busca de dados

Server Components

Você pode buscar dados em Server Components usando qualquer I/O assíncrono, como:

  1. A API fetch
  2. Um ORM ou banco de dados

Com a API fetch

Para buscar dados com a API fetch, transforme seu componente em uma função assíncrona e use await na chamada do fetch. Por exemplo:

app/blog/page.tsx
export default async function Page() {
  const data = await fetch('https://api.vercel.app/blog')
  const posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Bom saber:

  • Requisições fetch idênticas em uma árvore de componentes React são memorizadas por padrão, então você pode buscar dados no componente que precisa deles, em vez de passar props por vários níveis.
  • Requisições fetch não são armazenadas em cache por padrão e bloqueiam a renderização da página até que a requisição seja concluída. Use a diretiva use cache para armazenar os resultados em cache, ou envolva o componente que faz a busca em um <Suspense> para fazer streaming de dados atualizados no momento da requisição. Veja caching para mais detalhes.
  • Durante o desenvolvimento, você pode registrar as chamadas de fetch para ter mais visibilidade e facilitar a depuração. Veja a referência da API logging.

Com um ORM ou banco de dados

Como os Server Components são renderizados no servidor, credenciais e a lógica de consulta não são incluídas no bundle do cliente. Por isso, você pode fazer consultas ao banco de dados com segurança, usando um ORM ou um cliente de banco de dados.

app/blog/page.tsx
import { db, posts } from '@/lib/db'

export default async function Page() {
  const allPosts = await db.select().from(posts)
  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Você ainda deve garantir que as requisições estejam devidamente autenticadas e autorizadas. Para boas práticas de segurança no acesso a dados do lado do servidor, veja o guia de segurança de dados.

Streaming

Quando você busca dados em Server Components, os dados são buscados e renderizados no servidor a cada requisição. Se houver alguma requisição de dados lenta, a rota inteira fica bloqueada até que todos os dados sejam buscados.

Para melhorar o tempo de carregamento inicial e a experiência do usuário, você pode dividir a página em partes menores, chamadas chunks, e enviá-las progressivamente do servidor para o cliente. Isso se chama streaming. Veja o guia de Streaming para entender em mais detalhes como ele funciona, incluindo o contrato HTTP, considerações de infraestrutura e trade-offs de desempenho.

Como funciona a renderização no servidor com streamingComo funciona a renderização no servidor com streaming

Há duas formas de usar streaming no seu app:

  1. Envolvendo uma página com um arquivo loading.js
  2. Envolvendo um componente com <Suspense>

Bom saber: Bots e crawlers recebem um tratamento diferente dos navegadores. O Next.js espera a busca de dados terminar e envia a página totalmente renderizada, em vez de fazer streaming progressivo. Veja Bots e crawlers.

Com loading.js

Você pode criar um arquivo loading.js na mesma pasta da sua página para fazer streaming da página inteira enquanto os dados são buscados. Por exemplo, para fazer streaming de app/blog/page.js, adicione o arquivo dentro da pasta app/blog.

Estrutura da pasta blog com o arquivo loading.jsEstrutura da pasta blog com o arquivo loading.js
app/blog/loading.tsx
export default function Loading() {
  // Define the Loading UI here
  return <div>Loading...</div>
}

Na navegação, o usuário vê imediatamente o layout e um estado de carregamento enquanto a página é renderizada. O novo conteúdo é então substituído automaticamente quando a renderização termina.

Interface de carregamentoInterface de carregamento

Por baixo dos panos, o loading.js é aninhado dentro do layout.js e envolve automaticamente o arquivo page.js e todos os filhos abaixo dele em um limite de <Suspense>.

Visão geral do loading.jsVisão geral do loading.js

Por isso, um layout que acessa dados não armazenados em cache ou dados de runtime (por exemplo, cookies(), headers() ou fetch sem cache) não usa o loading.js do mesmo segmento de rota como fallback. Em vez disso, ele bloqueia a navegação até que o layout termine de renderizar. O Cache Components evita isso, orientando você com um erro em tempo de build.

Para corrigir, envolva o acesso não armazenado em cache no seu próprio limite de <Suspense> com um fallback, ou mova a busca de dados para o page.js, onde o loading.js consegue cobri-la. Veja loading.js para mais detalhes.

É por isso que, embora o loading.js funcione bem para fazer streaming de segmentos de rota, é recomendado usar <Suspense> mais próximo do acesso a dados de runtime ou não armazenados em cache.

Com <Suspense>

O <Suspense> permite controlar com mais granularidade quais partes da página fazem streaming. Por exemplo, você pode mostrar imediatamente qualquer conteúdo da página que esteja fora do limite de <Suspense> e fazer streaming da lista de posts do blog que está dentro dele.

app/blog/page.tsx
import { Suspense } from 'react'
import BlogList from '@/components/BlogList'
import BlogListSkeleton from '@/components/BlogListSkeleton'

export default function BlogPage() {
  return (
    <div>
      {/* This content will be sent to the client immediately */}
      <header>
        <h1>Welcome to the Blog</h1>
        <p>Read the latest posts below.</p>
      </header>
      <main>
        {/* If there's any dynamic content inside this boundary, it will be streamed in */}
        <Suspense fallback={<BlogListSkeleton />}>
          <BlogList />
        </Suspense>
      </main>
    </div>
  )
}

Criando estados de carregamento significativos

Um estado de carregamento instantâneo é a interface de fallback exibida ao usuário logo após a navegação. Para a melhor experiência, recomendamos criar estados de carregamento significativos, que ajudem o usuário a entender que o app está respondendo. Por exemplo, você pode usar skeletons e spinners, ou uma parte pequena, mas relevante, das telas futuras, como uma foto de capa, o título etc.

Em desenvolvimento, você pode visualizar e inspecionar o estado de carregamento dos seus componentes usando o React Devtools.

Client Components

Há duas formas de buscar dados em Client Components, usando:

  1. A API use do React
  2. Uma biblioteca da comunidade, como SWR ou React Query

Streaming de dados com a API use

Você pode usar a API use do React para fazer streaming de dados do servidor para o cliente. Comece buscando os dados no seu Server Component e passe a promise para o seu Client Component como prop:

app/blog/page.tsx
import Posts from '@/app/ui/posts'
import { Suspense } from 'react'

export default function Page() {
  // Don't await the data fetching function
  const posts = getPosts()

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Posts posts={posts} />
    </Suspense>
  )
}

Em seguida, no seu Client Component, use a API use para ler a promise:

app/ui/posts.tsx
'use client'
import { use } from 'react'

export default function Posts({
  posts,
}: {
  posts: Promise<{ id: string; title: string }[]>
}) {
  const allPosts = use(posts)

  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

No exemplo acima, o componente <Posts> está envolvido em um limite de <Suspense>. Isso significa que o fallback será exibido enquanto a promise estiver sendo resolvida. Saiba mais sobre streaming.

Você pode resolver uma promise no servidor com await ou em um Client Component com use(). O React explica quando resolver uma Promise em um Server ou Client Component. Para compartilhar uma mesma promise com vários Client Components, em vez de passá-la como prop, forneça-a por meio de context. Veja Usando o use do React dentro de um Context Provider.

Bibliotecas da comunidade

Você pode usar uma biblioteca da comunidade, como SWR ou React Query, para buscar dados em Client Components. Essas bibliotecas têm suas próprias semânticas de cache, streaming e outros recursos. Por exemplo, com SWR:

app/blog/page.tsx
'use client'
import useSWR from 'swr'

const fetcher = (url) => fetch(url).then((r) => r.json())

export default function BlogPage() {
  const { data, error, isLoading } = useSWR(
    'https://api.vercel.app/blog',
    fetcher
  )

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <ul>
      {data.map((post: { id: string; title: string }) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Veja Busca de dados no lado do cliente para buscas diretas no navegador, para fornecer dados iniciais a partir de um Server Component e para coordenar o cache de uma biblioteca com os caches do servidor e do cliente do Next.js.

Exemplos

Busca de dados sequencial

A busca de dados sequencial acontece quando uma requisição depende dos dados de outra.

Por exemplo, <Playlists> só pode buscar dados depois que getArtist() for resolvido, porque precisa do artistID:

app/artist/[username]/page.tsx
export default async function Page({
  params,
}: {
  params: Promise<{ username: string }>
}) {
  const { username } = await params
  // Get artist information
  const artist = await getArtist(username)

  return (
    <>
      <h1>{artist.name}</h1>
      {/* Show fallback UI while the Playlists component is loading */}
      <Suspense fallback={<div>Loading...</div>}>
        {/* Pass the artist ID to the Playlists component */}
        <Playlists artistID={artist.id} />
      </Suspense>
    </>
  )
}

async function Playlists({ artistID }: { artistID: string }) {
  // Use the artist ID to fetch playlists
  const playlists = await getArtistPlaylists(artistID)

  return (
    <ul>
      {playlists.map((playlist) => (
        <li key={playlist.id}>{playlist.name}</li>
      ))}
    </ul>
  )
}

Neste exemplo, o <Suspense> permite que as playlists façam streaming depois que os dados do artista carregam. No entanto, a página ainda espera pelos dados do artista antes de exibir qualquer coisa. Para evitar isso, você pode envolver o componente de página inteiro em um limite de <Suspense> (por exemplo, usando um arquivo loading.js) para mostrar um estado de carregamento imediatamente.

Garanta que sua fonte de dados consiga responder à primeira requisição rapidamente, pois ela bloqueia todo o resto. Se não for possível otimizar mais a requisição, considere armazenar em cache o resultado se os dados mudarem com pouca frequência.

Busca de dados paralela

A busca de dados paralela acontece quando as requisições de dados de uma rota são iniciadas de forma antecipada e começam ao mesmo tempo.

Por padrão, layouts e páginas são renderizados em paralelo. Assim, cada segmento começa a buscar dados o quanto antes.

No entanto, dentro de qualquer componente, várias requisições async/await ainda podem ser sequenciais se uma vier depois da outra. Por exemplo, getAlbums ficará bloqueado até que getArtist seja resolvido:

app/artist/[username]/page.tsx
import { getArtist, getAlbums } from '@/app/lib/data'

export default async function Page({ params }) {
  // These requests will be sequential
  const { username } = await params
  const artist = await getArtist(username)
  const albums = await getAlbums(username)
  return <div>{artist.name}</div>
}

Inicie várias requisições chamando fetch e depois aguarde todas com Promise.all. As requisições começam assim que o fetch é chamado.

app/artist/[username]/page.tsx
import Albums from './albums'

async function getArtist(username: string) {
  const res = await fetch(`https://api.example.com/artist/${username}`)
  return res.json()
}

async function getAlbums(username: string) {
  const res = await fetch(`https://api.example.com/artist/${username}/albums`)
  return res.json()
}

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

  // Initiate requests
  const artistData = getArtist(username)
  const albumsData = getAlbums(username)

  const [artist, albums] = await Promise.all([artistData, albumsData])

  return (
    <>
      <h1>{artist.name}</h1>
      <Albums list={albums} />
    </>
  )
}

Bom saber: Se uma requisição falhar ao usar Promise.all, a operação inteira falha. Para lidar com isso, você pode usar o método Promise.allSettled.

Reutilização de dados com React.cache

Para acesso a dados que não usa fetch, como uma consulta de ORM ou de banco de dados, envolva a função em React.cache. Assim, vários componentes podem chamar a função dentro da mesma requisição e compartilhar um único resultado:

app/lib/user.ts
import { cache } from 'react'
import { db, eq, users } from '@/lib/db'

export const getUser = cache(async (id: string) => {
  return db.query.users.findFirst({
    where: eq(users.id, id),
  })
})

Os Server Components podem chamar getUser() diretamente:

app/dashboard/page.tsx
import { getUser } from '../lib/user'

export default async function DashboardPage() {
  const user = await getUser('1')

  if (!user) {
    return null
  }

  return <h1>Dashboard for {user.name}</h1>
}

Como getUser está envolvido com React.cache, chamadas com o mesmo id dentro de uma requisição retornam o mesmo resultado memorizado.

Bom saber: O React.cache fica restrito à requisição atual. Cada requisição tem seu próprio escopo de memorização, sem compartilhamento entre requisições.

Pré-carregando dados

Quando um componente renderiza depois de outro trabalho bloqueante, sua requisição de dados começa tarde, mesmo que os dados necessários já estejam disponíveis. O pré-carregamento inicia a requisição mais cedo, para que ela rode em paralelo com esse trabalho e evite uma cascata de requisições (waterfall).

Para pré-carregar dados, chame a função de busca sem await antes do trabalho bloqueante e, depois, chame a mesma função no componente que consome o resultado.

A função de busca de dados precisa deduplicar as chamadas equivalentes para que o componente possa reutilizar a requisição iniciada durante o pré-carregamento. Use uma das abordagens a seguir:

Em produção, chamadas equivalentes a uma Cache Function privada podem reutilizar o mesmo resultado dentro de uma requisição. Isso permite que um componente reutilize uma requisição iniciada durante o pré-carregamento, sem armazenar o resultado em um cache do servidor entre requisições.

Mantenha a função de pré-carregamento ao lado do componente que consome os dados. Assim, a dependência fica mais fácil de encontrar se você mover ou remover o componente:

app/item/[id]/item.tsx
async function getItem(id: string) {
  const res = await fetch(`https://api.example.com/items/${id}`)
  return res.json()
}

export const preload = (id: string) => {
  void getItem(id)
}

export default async function Item({ id }: { id: string }) {
  const item = await getItem(id)
  return <div>{item.name}</div>
}

Chame preload() antes de outra requisição bloqueante para começar a carregar o item mais cedo:

app/item/[id]/page.tsx
import Item, { preload } from './item'
import { checkIsAvailable } from '@/app/lib/data'

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

  preload(id)
  const isAvailable = await checkIsAvailable(id)

  return isAvailable ? <Item id={id} /> : null
}

A requisição do item continua enquanto checkIsAvailable() roda. Se a página renderizar <Item>, a chamada fetch idêntica reutiliza a requisição que o preload() iniciou.

Próximos passos

Saiba mais sobre padrões avançados de busca de dados e os recursos mencionados nesta página.