Capítulo 156 de 456

connection

Core Idea

connection() sinaliza que a renderização deve esperar por uma requisição real do usuário antes de continuar, útil para componentes que produzem saída diferente por request (Math.random(), new Date()) sem usar Request-time APIs como cookies/headers.

Key Concepts

  • await connection(): retorna Promise<void>; interrompe o prerendering até chegar uma requisição real; código após ele só roda em request time.
  • Sem parâmetros e sem retorno útil: a Promise não deve ser consumida.
  • Substitui unstable_noStore: é a API alinhada com o futuro do Next.js.
  • Caso de uso típico: drivers de banco síncronos (ex. better-sqlite3) que completam a query durante o prerender; connection() força exclusão dessa query do prerender.
  • Com Cache Components: prefira io() para excluir conteúdo do static shell, pois também pode ser cacheado/prefetched; use connection() só quando a renderização realmente precisa esperar um request real.

Code Examples

import { connection } from 'next/server'

export default async function Page() {
  await connection() // prerendering stops here
  const rand = Math.random()
  return <span>{rand}</span>
}
  • O que demonstra: uso básico para forçar renderização em request time sem depender de Request-time APIs.
import { connection } from 'next/server'
import Database from 'better-sqlite3'

const db = new Database('app.db')

export async function getVisitorCount() {
  await connection()
  return db.prepare('SELECT value FROM counters WHERE name = ?').get('visitors')
}
  • O que demonstra: excluir do prerender uma query síncrona que, de outra forma, completaria durante o build.

Reference Tables

ItemValor
Assinaturafunction connection(): Promise<void>
Parâmetrosnenhum
RetornoPromise void, não deve ser consumida

Key Takeaways

  1. connection() só é necessária quando renderização dinâmica é obrigatória e nenhuma Request-time API comum está sendo usada.
  2. Qualquer componente que chame a função que usa connection() é excluído do prerender junto com o resto de sua saída.
  3. Em projetos com Cache Components, avalie io() primeiro; connection() é para o caso específico de esperar um request real.

Connects To

  • io: alternativa preferida sob Cache Components, com suporte a cache/prefetch.
  • unstable_noStore: API antecessora substituída por connection.
  • cookies / headers: Request-time APIs que também opt-in em dynamic rendering, mas por caminho diferente.
AnteriorcatchErrorPróximocookies