io

Core Idea

Com Cache Components habilitado, io() sinaliza ao Next.js que um valor síncrono não determinístico (new Date(), Math.random(), driver sync de DB) deve ser excluído do shell estático em vez de capturado nele.

Key Concepts

• io(): function io(): Promise<void>, sem parâmetros; await io() suspende durante o prerender (precisa de <Suspense> acima).
• Fora do prerender: em request real, dentro de escopos cacheados, no browser, ou em apps sem Cache Components, resolve imediatamente (no-op).
• Alternativa a "use cache": para capturar o valor no shell estático em vez de excluí-lo, envolva em 'use cache'.
• io() vs connection(): io() suspende como qualquer async function (o código após pode ser cacheado com use cache e prefetched); connection() fica suspenso até uma navegação real chegar ao servidor, bloqueando prefetches. Prefira io(); use connection() só quando precisar esperar por request real.

Code Examples

// app/page.tsx
import { Suspense } from 'react'
import { io } from 'next/cache'

export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <CurrentTime />
    </Suspense>
  )
}

async function CurrentTime() {
  await io()
  return <p>{new Date().toISOString()}</p>
}

• O que demonstra: excluir new Date() do shell estático — a fallback do Suspense é o que entra no prerender.

// Client Component: usar io() com o hook `use` do React
'use client'
import { use } from 'react'
import { io } from 'next/cache'

export function CurrentTime() {
  use(io())
  return <div>{Date.now()}</div>
}

• O que demonstra: Client Components também fazem SSR no prerender, então precisam de io() para não capturar valores não determinísticos no shell.

Key Takeaways

1. Não precisa de io() se o componente já usa uma Request-time API (cookies(), headers()) — essa já é o ponto de suspensão.
2. Não precisa se o dado vem de fetch/query async já dentro de <Suspense> — o await já é o ponto de suspensão.
3. Prefira io() a connection() sempre que o código seguinte puder ser cacheado e prefetched.

Reference Tables

Version	Changes
v16.3.0	io adicionado

Connects To

• connection(): alternativa que bloqueia prefetch, usar só quando precisa esperar request real.
• use cache: alternativa para capturar (em vez de excluir) o valor no shell estático.
• cacheComponents: flag que precisa estar ativa para io() ter efeito.