Real-time & Streaming Patterns in Next.js

Real-time applications feel alive. They show live notifications, collaborative cursors, streaming logs, and dashboards that update without a page refresh. Next.js gives you several ways to build this experience, but the right choice depends on latency, directionality, and whether the work happens on the server, the client, or both.

The App Router is fundamentally built around streaming. React Server Components, Suspense boundaries, and loading UI are all designed to let the server emit HTML progressively as data becomes ready. This is a form of real-time delivery, even if it is not bidirectional. For true two-way communication, you typically look outside the Next.js runtime to WebSockets, hosted real-time services, or carefully designed Server-Sent Events.

This guide covers the full landscape: why route handlers cannot hold long-lived WebSocket connections, how to push updates from the server with SSE, how to stream React Server Components, how Partial Prerendering gives you a static shell with dynamic holes, and how to structure clients so connections are shared, reconnected, and cleaned up correctly. The goal is a production mental model: pick the right primitive, keep the server stateless, and never leak connection lifecycle into the client without a plan.

WebSockets are the classic answer to real-time, bidirectional messaging. They keep a single TCP connection open and allow either side to push messages at any time. They are ideal for chat, collaborative editing, multiplayer games, and live operational dashboards where the client needs to send data as well as receive it.

Next.js route handlers cannot hold long-lived WebSocket connections. A route handler is a short-lived, stateless request/response function. When the response is sent, the function is done and the underlying server may recycle the process. There is no persistent socket object to keep alive. If you try to wedge a WebSocket server into a route handler, you will lose connections on every deployment, function timeout, or cold start.

The standard pattern is to run the WebSocket server outside the Next.js runtime. Options include Socket.io with a dedicated Node.js server, PartyKit on Cloudflare Workers, Ably, Pusher, or a custom WebSocket server behind a load balancer. The Next.js application connects to this external service as a client. This keeps the Next.js app stateless and scalable while the real-time service owns the connection state.

The example above keeps a single socket instance in module scope. This is important because multiple components on the same page should share one connection, not create a new connection per component. The trade-off is that cleanup becomes more careful: you unsubscribe from events but avoid disconnecting the socket unless the entire application is unmounting.

Server-Sent Events are a one-way push mechanism from server to client. They use ordinary HTTP, reconnection is built into the browser, and the protocol is text-based. SSE is perfect for notifications, log streams, progress bars, and live dashboards where the server does all the talking and the client only listens.

In a Next.js route handler, you implement SSE by returning a ReadableStream with the correct headers. The client uses the browser's EventSource API to connect. Unlike WebSockets, SSE is unidirectional and does not require a separate protocol upgrade, so it works well through proxies and load balancers.

The client side is a small hook built around EventSource. Always handle the error event, because the browser will automatically reconnect but you may need to re-establish authentication or context. The AbortController or a simple cleanup function lets you close the connection when the component unmounts.

One subtle issue with SSE is authentication. The browser EventSource does not support custom headers, so you cannot send a Bearer token directly. Workarounds include passing a short-lived token in the query string, using cookies with HttpOnly and SameSite, or falling back to a fetch-based streaming implementation with ReadableStream on the client.

Streaming React Server Components is one of Next.js's most powerful features. Instead of waiting for every data dependency to resolve before sending HTML, the server streams the shell of the page immediately and fills in the slow parts as they finish. The user sees content faster, and the Time to First Byte stays low even when one part of the page is slow.

The mechanism is Suspense. When a Server Component is wrapped in <Suspense>, React can emit the surrounding HTML and leave a placeholder for the deferred work. The placeholder is replaced when the promise resolves. This is not a persistent real-time connection like a WebSocket, but it is a form of progressive delivery that dramatically improves perceived performance.

You can nest Suspense boundaries to create a waterfall-free layout. The outer shell renders first, then each inner boundary resolves independently. This is especially useful for pages with many independent data sources: one slow query no longer blocks the rest of the page.

Next.js also provides a loading.tsx convention that wraps an entire route segment in a Suspense boundary. This is useful for coarse-grained loading states, but for fine-grained control, use explicit Suspense in your page components. The combination of route-level loading UI and component-level Suspense gives you a complete streaming strategy.

Partial Prerendering is an experimental Next.js feature that lets you build a static shell at build time and fill dynamic holes at request time. It combines the speed of static generation with the freshness of dynamic data. The shell is cached globally, while the dynamic holes stream in per request.

PPR is enabled in next.config.ts. Once enabled, any route that uses dynamic APIs such as cookies(), headers(), or uncached data fetches becomes a dynamic hole in an otherwise static page. The static parts are served from the edge cache; the dynamic parts are rendered on demand and streamed into the shell.

A typical PPR page looks like a normal streaming page with Suspense. The difference is that at build time, Next.js prerenders the static portions and records where dynamic holes should be injected. The first request receives the static shell immediately, and the dynamic holes stream in as they resolve.

PPR has compatibility constraints. It does not work with every middleware pattern, and some dynamic APIs force the entire route to be dynamic if used outside a Suspense boundary. As of Next.js 16, PPR remains experimental. Enable it for routes where the static shell is large and the dynamic parts are small and well-isolated.

The right primitive depends on the direction of data flow, latency requirements, and whether you need persistent state. WebSockets are not always better than SSE, and SSE is not always better than long polling. Start with the simplest mechanism that meets your latency budget and upgrade only when you have evidence it is needed.

For a chat application, WebSockets are the clear winner. For a stock ticker where the server pushes prices and the client never responds, SSE is simpler and cheaper. For a page that renders user-specific recommendations but is otherwise static, PPR is the best fit. For a simple progress indicator during a file upload, SSE over the upload route handler is often enough.

Real-time connections are a client-side concern. They must be created, shared, reconnected, and destroyed correctly. A common mistake is to create a new connection inside every component that needs it. This multiplies server load and makes state synchronization harder. Instead, use a module-level singleton or a context that owns the connection.

A robust WebSocket hook handles connection state, reconnection, message buffering, and cleanup. Keep the hook small and compose it from a shared socket manager. The hook should expose the connection state so UI can show disconnected indicators or disable inputs when offline.

For SSE, the pattern is similar but simpler because the browser manages reconnection. Your main responsibility is to close the connection on unmount and to handle the error event gracefully. If you need custom headers, fall back to a fetch-based stream reader instead of EventSource.

On the server, real-time usually means pub/sub and presence. A publish/subscribe layer decouples the event producers from the consumers. A presence layer tracks who is currently online. These are usually implemented with Redis, a managed real-time service, or a combination of both.

Next.js itself does not store connection state. The real-time server or service does. If you build a custom WebSocket server, you will likely use Redis Pub/Sub to broadcast messages across multiple server instances. When a user sends a message, it is published to a Redis channel; every WebSocket server subscribed to that channel forwards it to its connected clients.

Rate limiting is essential for real-time endpoints. A malicious or buggy client can spam events and overwhelm your server or pub/sub layer. Limit connections per IP, messages per connection, and burst rates per room. Apply the same validation rules to real-time payloads that you apply to HTTP request bodies.

Authentication for real-time connections should be checked at connection time and revalidated periodically. For Socket.io, use a middleware that verifies the token before allowing the connection. For SSE, validate the cookie or query token on the initial request and reject it if the session is invalid. Do not trust the client to identify itself in event payloads.

Real-time systems increase the attack surface. A persistent connection can be held open indefinitely, used as a DoS vector, or exploited to bypass HTTP security controls. The basic rules of web security still apply: validate inputs, authenticate users, and limit how much any single connection can do.

For WebSockets, configure the connection with sensible limits. Set a maximum payload size, enable per-message compression only if you need it, and close idle connections after a timeout. On the server, use a library that handles framing safely and protects against malformed frames.

For SSE, the biggest risk is information disclosure through the URL. If you pass a token as a query parameter, it may be logged by proxies or server logs. Prefer cookie-based authentication and terminate the connection immediately if the session becomes invalid. Use HTTPS for all real-time traffic so tokens and payloads cannot be intercepted.