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:
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:
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>
)
}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
fetchidê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
fetchnã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 diretivause cachepara 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
fetchpara ter mais visibilidade e facilitar a depuração. Veja a referência da APIlogging.
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.
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>
)
}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.

Há duas formas de usar streaming no seu app:
- Envolvendo uma página com um arquivo
loading.js - 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.

export default function Loading() {
// Define the Loading UI here
return <div>Loading...</div>
}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.

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>.

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.
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>
)
}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:
- A API
usedo React - 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:
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>
)
}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:
'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>
)
}'use client'
import { use } from 'react'
export default function Posts({ posts }) {
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:
'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>
)
}'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) => (
<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:
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>
)
}export default async function Page({ params }) {
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 }) {
// 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:
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.
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} />
</>
)
}import Albums from './albums'
async function getArtist(username) {
const res = await fetch(`https://api.example.com/artist/${username}`)
return res.json()
}
async function getAlbums(username) {
const res = await fetch(`https://api.example.com/artist/${username}/albums`)
return res.json()
}
export default async function Page({ params }) {
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étodoPromise.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:
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),
})
})import { cache } from 'react'
import { db, eq, users } from '@/lib/db'
export const getUser = cache(async (id) => {
return db.query.users.findFirst({
where: eq(users.id, id),
})
})Os Server Components podem chamar getUser() diretamente:
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>
}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.cachefica 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:
- Para
fetch, requisições idênticas são memorizadas automaticamente. - Para um ORM ou banco de dados, envolva a função de busca de dados em
React.cache. - Com Cache Components, adicione
'use cache'à função de busca de dados. Se a função ler APIs de requisição, comocookies()ouheaders(), use'use cache: private'.
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:
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>
}async function getItem(id) {
const res = await fetch(`https://api.example.com/items/${id}`)
return res.json()
}
export const preload = (id) => {
void getItem(id)
}
export default async function Item({ id }) {
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:
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
}import Item, { preload } from './item'
import { checkIsAvailable } from '@/app/lib/data'
export default async function Page({ params }) {
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.