Transmite la salida del modelo con Server-Sent Events desde un route handler de Next.js

Esperar diez segundos por un muro de texto se siente como si la app se hubiera colgado. Transmitir esa misma respuesta token por token se siente instantáneo, aunque el tiempo total sea idéntico. Esta guía arma el streaming de extremo a extremo en el App Router de Next.js: un route handler que devuelve un ReadableStream conectado al SDK de Claude, el formato de Server-Sent Events que aguanta el paso por los reverse proxies, un cliente en el navegador que lee el stream y va pintando los deltas, y el puñado de fallas de producción, buffering, requests que quedan colgados, el runtime equivocado, que dejan el streaming roto de maneras que nunca vas a ver en localhost.

01 · Requisitos y el modelo mental

Antes de escribir una línea de código, dos cosas tienen que estar dadas y una tiene que quedarte clara.

El modelo mental es la parte que la gente se salta, y por eso terminan con el stream roto. Una respuesta HTTP normal es un solo body: el servidor calcula todo, le pone un content-length y lo manda. El streaming le da la vuelta a eso. El servidor manda un body de longitud desconocida, por partes, sobre una conexión que mantiene abierta. Tres cosas tienen que jugar juntas para que el usuario vea llegar los tokens:

1. El route handler genera los chunks de a poco y va soltando cada uno, en vez de bufferizar la respuesta completa.
2. Nada en el camino entre el handler y el navegador, ni Next.js, ni un reverse proxy, ni un CDN, junta esos chunks en una sola respuesta antes de reenviarla.
3. El cliente lee el body como un stream en lugar de llamar a response.text(), que espera hasta el final.

Si se rompe cualquiera de los tres, el usuario no ve nada hasta que el modelo termina por completo, que es justo el comportamiento que querías evitar. La mayoría de los bugs de "mi stream no transmite" están en el eslabón dos, y volvemos a eso en la sección 05.

02 · Lo más simple que funciona: un stream de texto plano

Arranca con la menor cantidad de maquinaria posible. En el App Router, un route handler puede devolver un Response cuyo body es un ReadableStream. Armas el stream, vas encolando texto codificado a medida que el modelo lo produce, y lo cierras al terminar.

import Anthropic from "@anthropic-ai/sdk"

export const runtime = "nodejs"

const client = new Anthropic()

export async function POST(req: Request) {
  const { messages } = await req.json()
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      const run = client.messages.stream({
        model: "claude-sonnet-4-6",
        max_tokens: 1024,
        messages,
      })
      run.on("text", (delta) => controller.enqueue(encoder.encode(delta)))
      await run.finalMessage()
      controller.close()
    },
  })

  return new Response(stream, {
    headers: {
      "content-type": "text/plain; charset=utf-8",
      "cache-control": "no-store",
    },
  })
}

Acá hay tres cosas que hacen el trabajo pesado. El client.messages.stream() del SDK devuelve un helper que emite un evento text por cada delta: no parseas el SSE crudo de Anthropic a mano, el SDK ya lo hizo por ti. controller.enqueue() empuja un chunk codificado al body de la respuesta apenas existe. Y controller.close() no es opcional: si te olvidas, el navegador se queda esperando un final que nunca llega, aunque cada token ya haya llegado. Fíjate que acá el runtime es nodejs; comparamos contra el runtime edge en la sección 06.

Este enfoque de texto plano está más que bien para un endpoint de chat de un solo propósito. El body es solo el texto de la respuesta; el cliente concatena los chunks y los pinta. Recurres a más estructura solo cuando necesitas mandar algo más que texto por el cable, que es de lo que va la siguiente sección.

03 · Cuando el texto plano no alcanza: Server-Sent Events de verdad

El texto plano te da un solo canal: la respuesta. Las aplicaciones reales suelen necesitar más: una forma de distinguir "acá va un token" de "acá va un error" de "acá va el conteo final de tokens", e idealmente una forma de que el navegador reconecte tras una caída sin tener que reenviar todo el prompt. Eso es lo que te da Server-Sent Events, y es un formato pequeño y bien especificado.

El formato del cable SSE

SSE es texto plano con apenas un par de reglas. Cada mensaje es un bloque de líneas; una línea en blanco cierra el bloque. Los campos que de verdad vas a usar:

• data: el payload (uno por línea; varias líneas data: en un mismo bloque se unen con saltos de línea).
• event: un nombre opcional, para que el cliente mande cada tipo de mensaje al handler que le toca.
• id: un id opcional que el navegador guarda y reenvía como Last-Event-ID al reconectar.
• retry: un retraso opcional de reconexión, en milisegundos.

Acá tienes la misma ruta, ahora hablando SSE con eventos con nombre para tokens, finalización y errores:

import Anthropic from "@anthropic-ai/sdk"

export const runtime = "nodejs"

const client = new Anthropic()

function sse(event: string, data: unknown) {
  return "event: " + event + "\n" + "data: " + JSON.stringify(data) + "\n\n"
}

export async function POST(req: Request) {
  const { messages } = await req.json()
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      const send = (e: string, d: unknown) =>
        controller.enqueue(encoder.encode(sse(e, d)))
      try {
        const run = client.messages.stream({
          model: "claude-sonnet-4-6",
          max_tokens: 1024,
          messages,
        })
        run.on("text", (delta) => send("token", delta))
        const final = await run.finalMessage()
        send("done", { usage: final.usage })
      } catch (err) {
        send("error", { message: "stream failed" })
      } finally {
        controller.close()
      }
    },
  })

  return new Response(stream, {
    headers: {
      "content-type": "text/event-stream; charset=utf-8",
      "cache-control": "no-store",
      "connection": "keep-alive",
    },
  })
}

El content-type ahora es text/event-stream, que es la señal que usan los navegadores y (lo más importante) los proxies para reconocer que esto es un stream. Cada mensaje es un bloque SSE bien cerrado que termina con un doble salto de línea, si te olvidas de la línea en blanco, el cliente nunca dispara el evento, porque el bloque nunca se da por completo.

Los heartbeats evitan que la conexión se muera

Las conexiones SSE inactivas se terminan cortando: las cortan los navegadores, los balanceadores de carga, los proxies con timeouts de lectura. Si tu modelo se demora en arrancar a producir tokens (pensando, o en una llamada lenta a una herramienta), la conexión se puede caer antes del primer byte. Una línea de comentario, una línea que arranca con dos puntos, es un keep-alive SSE inofensivo que el cliente ignora. Manda uno cada 15 segundos mientras esperas y la conexión se mantiene viva.

04 · El cliente: lee el stream y pinta los deltas

Un stream que el navegador junta todo de golpe no es un stream. La solución es ir leyendo el body de la respuesta de a poco. Para texto plano o para SSE sobre fetch, usa el reader del body directamente:

async function streamChat(messages: unknown[], onToken: (t: string) => void) {
  const res = await fetch("/api/chat", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ messages }),
  })
  if (!res.body) throw new Error("no response body")

  const reader = res.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ""

  while (true) {
    const { value, done } = await reader.read()
    if (done) break
    buffer += decoder.decode(value, { stream: true })

    // Separa por el delimitador de bloque SSE; guarda el parcial final en el buffer.
    const blocks = buffer.split("\n\n")
    buffer = blocks.pop() ?? ""
    for (const block of blocks) {
      const data = block
        .split("\n")
        .filter((l) => l.startsWith("data:"))
        .map((l) => l.slice(5).trim())
        .join("\n")
      if (data) onToken(JSON.parse(data))
    }
  }
}

El detalle con el que tropieza todo el mundo: los chunks de la red no caen alineados con los límites de los mensajes. Un solo reader.read() te puede entregar medio bloque SSE, o dos bloques y medio. Por eso vas acumulando en un buffer, separas por el delimitador de doble salto de línea, y te guardas el fragmento que sobre para la próxima lectura. Si te saltas esto, vas a terminar haciendo JSON.parse de medio token y reventando de forma intermitente, ese tipo de bug que solo aparece bajo condiciones reales de red, nunca en localhost.

Si te fuiste por SSE de verdad sobre una ruta GET, el cliente queda más simple: const es = new EventSource("/api/chat"), y después es.addEventListener("token", ...) y es.addEventListener("done", () => es.close()). La reconexión y el enrutamiento de eventos te salen gratis. Lo que pagas a cambio es la restricción de solo GET y sin body de la sección 03.

05 · El detalle que te roba una tarde entera: el buffering

Esta es, por lejos, la razón más común de que el streaming "no funcione" en producción mientras anda perfecto en localhost. Algo entre tu handler y el navegador está juntando la respuesta completa antes de reenviarla, así que el usuario espera todo el tiempo que tarde y después recibe todo de golpe, visualmente idéntico a no tener streaming.

Los sospechosos de siempre, más o menos por orden de probabilidad:

1. Un reverse proxy bufferizando la respuesta. nginx bufferiza las respuestas proxeadas por defecto. La solución es desactivarlo para la ruta de streaming: pon proxy_buffering off (o emite el header de respuesta X-Accel-Buffering: no, que nginx respeta). En Traefik, confirma que no haya un middleware de buffering enganchado al router que sirve la ruta.
2. Middleware de compresión. Un middleware de gzip/brotli que bufferiza para comprimir todo el body te tira abajo el streaming. Saca las rutas de streaming de la compresión, o apóyate en que text/event-stream no se comprima.
3. Tu propio código juntando el stream. Cualquier helper que haga await collect(stream) hacia un string, o un wrapper de analytics que lea el body para registrarlo, te vuelve a convertir el stream en una sola respuesta. Revisa bien el camino que toma la respuesta después de que el handler retorna.

Como el síntoma (anda en local, roto en prod) apunta hacia el lado contrario de la causa real (un proxy que no escribiste tú), este bug te roba una tarde sin falta. Revísalo de primero cuando un stream que andaba en dev empieza a llegar todo de golpe en producción.

06 · Runtime, cancelación, y no dejar requests colgados

Dos temas de producción que los ejemplos del camino feliz se saltan.

Edge vs Node runtime. El runtime edge arranca rápido y transmite bien, pero no puede usar APIs exclusivas de Node y tiene límites más estrictos. Algunas funciones del SDK, los módulos nativos y las conexiones de larga duración se comportan distinto o directamente no están disponibles. El runtime nodejs es el default seguro para una ruta que mantiene una conexión abierta mientras el modelo genera y, encima, puede llamar herramientas. Opta por edge solo cuando hayas confirmado que todo en el camino es compatible con Web APIs y de verdad quieras los beneficios de arranque en frío y geografía que da el edge. Déjalo explícito con export const runtime para que la decisión se vea, en vez de heredarse.

Cancelación. Cuando un usuario cierra la pestaña o se va a mitad de la respuesta, el navegador aborta el request, pero, a menos que lo escuches, tu handler sigue transmitiendo tokens del modelo al vacío. Te cobran por una salida que nadie va a ver. La solución es el AbortSignal del request: pásalo para que un abort también tumbe la llamada al modelo.

export async function POST(req: Request) {
  const { messages } = await req.json()
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      const run = client.messages.stream(
        { model: "claude-sonnet-4-6", max_tokens: 1024, messages },
        { signal: req.signal },
      )
      run.on("text", (d) => {
        if (!req.signal.aborted) controller.enqueue(encoder.encode(d))
      })
      try {
        await run.finalMessage()
      } catch {
        // Abortado o error upstream — sigue de largo y cierra.
      } finally {
        controller.close()
      }
    },
    cancel() {
      // El navegador se desconectó — el AbortSignal ya se propagó al SDK.
    },
  })

  return new Response(stream, {
    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
  })
}

Pasarle req.signal a la llamada del SDK hace que un request abortado se propague hasta Anthropic y corte la generación. El callback cancel() del stream se dispara cuando el consumidor se va, y te da un lugar para limpiar cualquier otra cosa. Sin este cableado, unos pocos usuarios que se van rápido se te vuelven una cuenta de tokens constante e invisible, y en un solo VPS, conexiones upstream que estás manteniendo abiertas para nada.

El streaming es una de esas funciones que son fáciles de demostrar y fáciles de subir a producción sutilmente rotas. Acierta la cadena de tres eslabones (incremental en el servidor, sin buffering en el medio, leído como stream en el cliente) y elige el formato de cable acorde a lo que de verdad necesitas mandar. Después pruébalo donde va a correr de verdad, no donde es cómodo, y deja cableada la cancelación antes de que el primer usuario real le dé al botón de atrás.