RFC: WebSocket Upgrades in Route Handlers

[timneutkens]

• Status: Draft
• Target: Experimental
• Scope: App Router Route Handlers
• Proposed API: NextResponse.upgrade()

Summary

This RFC proposes first-class WebSocket support in App Router Route Handlers:

import { NextResponse } from 'next/server'

export function GET(request: Request) {
  if (!isAuthorized(request)) {
    return new Response('Unauthorized', { status: 401 })
  }

  const response = NextResponse.upgrade({
    open(peer) {
      peer.send({ message: 'Welcome' })
    },

    message(peer, message) {
      peer.send(message.text())
    },

    close(peer, event) {
      console.log('closed', peer.id, event)
    },

    error(peer, error) {
      console.error(error)
    },
  })

  response.cookies.set('connected', 'true')
  response.headers.set('x-connection-id', crypto.randomUUID())

  return response
}

The handler executes exactly once per handshake. Returning an ordinary Response rejects the upgrade with that response. Returning NextResponse.upgrade() accepts the connection after the handler completes.

Every accepted connection receives a real CrossWS Peer created by Next.js’s bundled CrossWS Node adapter. Applications use the CrossWS peer, message, and lifecycle-hook APIs rather than the underlying ws.WebSocket API.

Self-hosted Next.js handles this through Node.js’s HTTP upgrade event. Adapters support it by forwarding the raw upgrade primitives to the generated App Route upgrade handler.

Motivation

Next.js currently has no first-class way for an App Route Handler to accept an incoming WebSocket connection.

Users must instead:

• Create a custom Node.js server.
• Register their own upgrade listener.
• Reimplement routing and authentication outside route.ts.
• Ensure application WebSockets do not conflict with Next.js development WebSockets.
• Use different application structures when moving between self-hosting and an Adapter.

A first-class API should satisfy these requirements:

1. The handler can inspect the incoming Request before accepting.
2. Authentication and authorization can return ordinary HTTP responses.
3. Headers and cookies can be included in the 101 handshake.
4. The connection is not accepted until the handler returns.
5. The Route Handler executes once per handshake.
6. Routing, proxy.ts, rewrites, instrumentation, and error handling remain part of Next.js.
7. Self-hosted and Adapter deployments use the same user-facing API.

Goals

• Support WebSockets from route.ts.
• Preserve ordinary Route Handler control flow.
• Support conditional acceptance.
• Support response headers and cookies.
• Provide the CrossWS Peer and Message APIs.
• Support route-wide peer tracking and publish/subscribe behavior.
• Work with next dev, next start, standalone output, and compatible Adapters.
• Avoid requiring users to create a custom server.

Non-goals

• Pages Router API route support
• Accepting WebSockets directly from proxy.ts.
• Edge runtime support.
• Adding WebSocket support to Adapters that cannot expose Node.js upgrade primitives or persistent sockets.
• Cross-instance pub/sub or connection coordination.
• Durable connections across deployments or process restarts.
• Exposing or guaranteeing the underlying raw ws object.
• Per-handshake payload, compression, or subprotocol configuration initially.

Proposed API

export type WebSocketPeer =
  import('next/dist/compiled/crossws').Peer

export type WebSocketMessage =
  import('next/dist/compiled/crossws').Message

export type WebSocketError =
  import('next/dist/compiled/crossws').WSError

export interface WebSocketCloseDetails {
  code?: number
  reason?: string
}

export type WebSocketHooks = Pick<
  Partial<import('next/dist/compiled/crossws').Hooks>,
  'open' | 'message' | 'close' | 'error'
>

class NextResponse extends Response {
  static upgrade(hooks: WebSocketHooks): NextResponse<null>
}

The hooks object can implement any of these lifecycle callbacks:

• open(peer) after the handshake succeeds.
• message(peer, message) when a message arrives.
• close(peer, details) when the connection closes.
• error(peer, error) for transport errors.

CrossWS peers provide send(), close(), terminate(), subscribe(), unsubscribe(), and publish(). Messages provide conversion helpers including text(), json(), uint8Array(), and arrayBuffer().

Plain objects passed to peer.send() or peer.publish() are serialized as JSON.

Next.js pins and bundles CrossWS 0.4.4 with its declarations, so applications do not need to install crossws, ws, or their type packages. peer.websocket remains CrossWS’s compatibility proxy; Next.js does not expose or guarantee raw ws event-emitter, ping, pong, or constructor-identity behavior.

peer.request uses CrossWS’s Node Request-compatible view. The complete incoming request remains available before acceptance through the Route Handler’s Request argument.

CrossWS Integration

Each generated App Route module owns one shared CrossWS Node adapter. Connections handled by the same route therefore participate in CrossWS peer tracking, subscriptions, and publication.

CrossWS namespaces default to the resolved request pathname. Dynamic route instances with different pathnames are isolated by default.

message(peer, message) {
  if (message.text() === 'join') {
    peer.subscribe('updates')
  }

  if (message.text() === 'publish') {
    peer.publish('updates', { type: 'refresh' })
  }
}

The initial implementation uses fixed transport settings:

• Per-message deflate: disabled.
• Peer tracking: enabled within the route’s shared CrossWS adapter.
• Subprotocol selection: not exposed.

Per-handshake transport options are not exposed because creating separate server instances would fragment route-wide peer tracking and publish/subscribe behavior.

Response Semantics

Conditional acceptance

export function GET(request: Request) {
  if (request.headers.get('origin') !== '<https://example.com>') {
    return new Response('Forbidden', { status: 403 })
  }

  return NextResponse.upgrade({
    open(peer) {
      peer.send('connected')
    },
  })
}

For a WebSocket handshake:

1. Node.js emits the upgrade event.
2. Next.js resolves and executes the Route Handler.
3. The handler returns 403.
4. Next.js writes that HTTP response directly to the socket.
5. No connection lifecycle hook is called.
6. The socket is closed.

Browser WebSocket APIs report a failed connection and generally do not expose the HTTP status or body. Node.js WebSocket clients can observe the early HTTP response through their client-specific APIs.

Successful acceptance

When the handler returns an upgrade response:

1. The handler finishes executing.
2. Next.js reads the final headers and cookies.
3. Next.js passes the upgrade to the route module’s shared CrossWS Node adapter.
4. The 101 response is written.
5. CrossWS creates the peer and invokes open(peer).

No lifecycle hook runs before the handler returns the upgrade response and the handshake succeeds.

Headers and cookies

const response = NextResponse.upgrade({
  open(peer) {
    peer.send('connected')
  },
})

response.headers.set('x-connection-id', id)
response.cookies.set('session', token, {
  httpOnly: true,
  sameSite: 'lax',
})

return response

Mutations made before returning the response are included in the handshake. Mutations made after returning have no effect.

Next.js controls these protocol-critical headers:

• Connection
• Upgrade
• Sec-WebSocket-Accept
• Sec-WebSocket-Extensions
• Sec-WebSocket-Protocol
• Content-Length
• Transfer-Encoding

Subprotocol selection is not exposed in the initial API.

Hook errors

Lifecycle hooks run after the handshake. Their errors cannot be converted into an HTTP response.

Synchronous exceptions and rejected promises from open, message, or error:

• Are reported through Next.js request-error instrumentation.
• Close the connection with code 1011.
• Do not expose internal error details in the close reason.

Errors from close are reported without attempting to close the peer again.

Fallible initialization should happen before returning:

export async function GET(request: Request) {
  const session = await authenticate(request)

  if (!session) {
    return new Response('Unauthorized', { status: 401 })
  }

  return NextResponse.upgrade({
    open(peer) {
      attachSession(peer, session)
    },
  })
}

Next.js observes hook promises for rejection but does not include them in the Route Handler request lifetime.

Self-hosted Node.js Behavior

Node.js handles upgrade requests separately from ordinary requests. A valid WebSocket handshake emits upgrade instead of request.

The Route Handler therefore executes once:

Ordinary GET        → request event → GET() once
WebSocket handshake → upgrade event → GET() once

next dev

Next.js already handles development WebSockets such as HMR.

Upgrade routing must preserve this order:

1. Apply development origin checks.
2. Handle internal HMR paths.
3. Resolve rewrites and application routing.
4. Invoke a matching App Route.
5. Preserve unmatched upgrade fallthrough for custom servers.

Application WebSocket paths must not interfere with /_next/hmr or other internal channels.

next start

The production Node.js server:

1. Receives the upgrade event.
2. Runs normal route resolution.
3. Applies proxy.ts, redirects, and rewrites.
4. Resolves the matching App Route.
5. Executes its GET handler.
6. Sends either an ordinary HTTP response or accepts the connection through CrossWS.

The current router closes upgrade requests that resolve to application routes. This branch would instead invoke the matching App Route.

Standalone output

Standalone output includes the same router and Node.js upgrade integration.

The output trace must include Next.js’s bundled CrossWS Node adapter and its required supporting files.

Custom servers

Custom servers using Next.js’s upgrade handling receive the same behavior.

Custom servers that bypass Next.js’s upgrade handler remain responsible for forwarding:

req
socket
head

into Next.js.

Existing unrelated upgrade listeners continue receiving paths that Next.js does not handle.

Ordinary HTTP requests

If a handler returns NextResponse.upgrade() from the normal HTTP request path, no upgrade socket is available.

Next.js returns:

HTTP/1.1 426 Upgrade Required
Upgrade: websocket

Shutdown

Next.js tracks accepted CrossWS peers by their canonical App Route bundle path.

During graceful shutdown:

• Connections receive close code 1001 where possible.
• Next.js waits for a bounded grace period.
• Remaining peers are terminated.
• Connections cannot indefinitely prevent process shutdown.

When a route is invalidated in development, its peers receive close code 1012. Next.js waits up to five seconds before terminating remaining peers. New connections use the updated route module, while internal HMR WebSockets remain unaffected.

Adapter Behavior

Build-time Adapters API

The build-time NextAdapter interface and AdapterOutput shape do not need to change.

WebSocket acceptance is a possible runtime result of an App Route, just like an ordinary response.

Adapters continue receiving the existing output:

{
  type: AdapterOutputType.APP_ROUTE,
  runtime: 'nodejs',
  filePath,
  pathname,
  assets,
  config,
}

No capability field is proposed. Conditional calls to NextResponse.upgrade() cannot be reliably identified at build time.

Full-server Adapters

Adapters deploying the complete Next.js Node.js server receive WebSocket support through the server’s upgrade handling.

The Adapter must ensure that its deployed environment allows the Node.js HTTP server to receive raw upgrade events and maintain long-lived TCP connections.

No App Route-specific integration is required.

Individual App Route outputs

The existing Node.js App Route entrypoint handles ordinary requests:

export async function handler(
  req: IncomingMessage,
  res: ServerResponse,
  ctx: HandlerContext
): Promise<void>

A Node.js upgrade event provides:

req: IncomingMessage
socket: Duplex
head: Buffer

It does not provide a ServerResponse.

Generated Node.js App Route outputs therefore gain an additive, Adapter-facing entrypoint:

export async function upgradeHandler(
  context: AppRouteHandlerContext,
  transport: {
    node: {
      req: IncomingMessage
      socket: Duplex
      head: Buffer
    }
  }
): Promise<void>

An Adapter that invokes individual route outputs must forward the raw upgrade event to this entrypoint.

The upgrade handler:

1. Creates the Route Handler Request.
2. Executes the same App Route module used for ordinary requests.
3. Detects an ordinary or upgrade response.
4. Sends an ordinary response or passes the upgrade to the module-scoped CrossWS adapter.
5. Dispatches the route’s hooks through CrossWS lifecycle events.

Unsupported Adapters

An Adapter that knows it cannot provide these capabilities must disable the feature through its existing modifyConfig hook:

import type { NextAdapter } from 'next'

const adapter: NextAdapter = {
  name: 'example-adapter',
  modifyConfig(config) {
    config.experimental.webSocketRouteHandlers = false
    return config
  },
}

export default adapter

modifyConfig runs after the application configuration is resolved, so the Adapter override takes precedence even if the application enables the experimental flag. No WebSocket capability field is added to NextAdapter or AdapterOutput.

When the Adapter disables the flag, calling NextResponse.upgrade() throws the normal flag-disabled configuration error in development and production. The error occurs when the Route Handler executes that code path; disabling the flag does not make the application fail at startup solely because WebSocket Route Handler code exists.

If a generated upgrade handler is nevertheless invoked without the required raw Node.js primitives or persistent socket support, it produces:

HTTP/1.1 501 Not Implemented

Next.js also logs a descriptive runtime error. This is a defensive fallback rather than the Adapter’s primary feature-disabling mechanism.

Adapter behavior matrix

Deployment	Behavior
next dev	Supported
next start	Supported
Standalone Node.js output	Supported
Custom server forwarding upgrades to Next.js	Supported
Adapter deploying the complete Node.js server	Supported when raw upgrades and persistent sockets are available
Adapter invoking individual Node.js App Routes	Must invoke the generated upgradeHandler
Adapter without Node.js upgrade primitives	Disables experimental.webSocketRouteHandlers through modifyConfig; use throws the flag-disabled error
Edge runtime	Unsupported
Static export	Build error

Routing and proxy.ts

Upgrade requests use the existing routing order:

1. Headers and redirects
2. proxy.ts
3. Rewrites
4. Filesystem and dynamic route matching
5. App Route execution
6. Proxying or unmatched-upgrade fallthrough

proxy.ts can allow, rewrite, redirect, or reject a handshake. NextResponse.upgrade() is only valid in App Route Handlers and is not supported from proxy.ts.

If proxy.ts returns an ordinary response, that response rejects the handshake.

Internal Next.js WebSocket paths retain priority over application routes.

Caching and Static Generation

Upgrade responses cannot be cached or prerendered.

Calling NextResponse.upgrade() marks the route dynamic and sets its effective revalidation behavior to zero. Calling it conditionally during a revalidation will be a runtime error.

The following produce an error if an upgrade response is encountered during static generation:

• output: 'export'
• dynamic = 'force-static'
• Prerendering the Route Handler

The entire Route Handler is treated as dynamic, even if some branches return ordinary cacheable responses.

Security Considerations

Applications should validate:

• Origin
• Authentication cookies or tokens
• Tenant and authorization information
• Incoming message size and shape

Next.js does not automatically enforce same-origin WebSockets in production.

The response cannot override protocol-critical handshake headers.

The internal upgrade marker must use private framework state rather than a forgeable incoming header.

Per-message compression defaults to disabled. Incoming payload size is bounded by default.

Upgrade Response Representation

Node.js’s Response implementation does not permit status code 101.

NextResponse.upgrade() must therefore return a framework response carrying:

• The four public CrossWS lifecycle hooks
• Handshake headers
• Response cookies

The object:

• Is accepted by App Route response validation.
• Has no body.
• Exposes headers and cookies.
• Is detected before ordinary response serialization.
• Produces status 101 only at the Node.js transport layer.

Generic reconstruction may lose the upgrade metadata:

new Response(response.body, response)

Next.js must inspect the result before cloning, caching, serializing, or reconstructing it.

Detailed Node.js Execution

Conceptually, each generated App Route module owns one shared adapter:

import crossws from 'next/dist/compiled/crossws/adapters/node'

const websocket = crossws({
  hooks: {
    open(peer) {
      registerPeer(peer)
      dispatchHook('open', peer)
    },
    message(peer, message) {
      dispatchHook('message', peer, message)
    },
    close(peer, event) {
      unregisterPeer(peer)
      dispatchHook('close', peer, event)
    },
    error(peer, error) {
      dispatchHook('error', peer, error)
    },
  },
})

server.on('upgrade', async (req, socket, head) => {
  const result = await executeAppRoute(req)

  if (!isUpgradeResponse(result)) {
    await writeHttpResponseToSocket(socket, result)
    return
  }

  attachUpgradeMetadata(req, {
    hooks: getUpgradeHooks(result),
    headers: result.headers,
  })

  websocket.handleUpgrade(req, socket, head)
})

An internal CrossWS upgrade hook transfers the returned response headers, cookies, and private per-connection metadata into the handshake. It is not exposed publicly because the Route Handler GET remains the sole pre-acceptance authentication and response phase.

NextResponse.upgrade() stores the hooks directly on the returned response. No hook registry or second Route Handler execution is required.

Trade-offs

Benefits

• Authentication happens before acceptance.
• Early ordinary responses use familiar Route Handler control flow.
• Cookies and headers use existing NextResponse APIs.
• The handler executes exactly once.
• Returning the response is the handshake commit point.
• Users receive a higher-level peer and message API with conversion helpers.
• Route-wide subscriptions and publication work across connections.
• Self-hosted and compatible Adapter deployments share one application API.
• Existing routing and proxy.ts behavior is preserved.

Considerations

• Route execution and connection ownership must remain in one Node.js process.
• Individual-route Adapters must integrate an additive upgrade entrypoint.
• Hook failures happen after the handshake.
• Long-lived connections complicate process shutdown and deployment draining.
• In-memory connection state does not automatically span instances.
• Static generation and caching are unavailable.
• Payload limits and compression settings are fixed initially.
• Subprotocol selection is not exposed initially.
• Raw ws event-emitter, ping, and pong APIs are not part of the supported contract.
• peer.websocket is CrossWS’s compatibility proxy and may vary across runtimes.

Alternatives Considered

Separate route export

export function UPGRADE(
  request: Request,
  peer: WebSocketPeer
) {}

This makes conditional ordinary responses, cookies, and response headers less natural. It also introduces a method-like export that is not an HTTP method.

request.upgrade()

const webSocket = request.upgrade()

This implies immediate acceptance and makes the point at which the handshake is committed less clear.

Dedicated websocket.ts convention

A separate file would make upgrade routes easier to identify statically, but it would split related HTTP authentication and WebSocket behavior across files.

Custom server only

Users can register server.on('upgrade'), but that bypasses Route Handler routing and does not provide consistent Adapter integration.

Expose ws.WebSocket directly

NextResponse.upgrade((webSocket) => {
  webSocket.on('message', () => {})
})

This closely matches the underlying Node.js transport, but makes a low-level, runtime-specific API public and provides no common peer, message, namespace, or publication abstraction.

Expose the CrossWS upgrade hook

CrossWS has a pre-acceptance upgrade hook. Exposing it would create a second authentication and response phase after the App Route GET handler.

The Route Handler already provides request inspection, conditional responses, cookies, and headers, so only the four connection lifecycle hooks are public.

Create one CrossWS adapter per connection

This would make per-handshake payload and compression settings straightforward, but subscriptions, publication, and peer tracking would not work across route connections. One shared adapter per generated route is preferred.

Application-installed CrossWS

Next.js could require applications to install CrossWS and supply their own adapter instance.

This introduces version compatibility, output tracing, and dependency-resolution concerns. Next.js’s pinned CrossWS build provides a deterministic peer and message contract without an application dependency.

Rollout

1. Add experimental.webSocketRouteHandlers.
2. Bundle and pin CrossWS with its declarations.
3. Implement next dev, next start, and standalone support.
4. Add the Adapter-facing Node.js App Route upgradeHandler export.
5. Validate full-server and individual-route Adapter integrations.
6. Validate an unsupported Adapter disabling the feature through modifyConfig.
7. Gather feedback on hook ergonomics, shutdown, subprotocols, and development behavior.
8. Stabilize after the Node.js and Adapter contracts are proven.

Test Plan

• Generate a dedicated App Router e2e suite.
• Verify next dev and next start.
• Verify Turbopack and webpack.
• Verify standalone output.
• Verify one GET execution per handshake.
• Verify ordinary 401, 403, redirect, and body responses.
• Verify response cookies and custom handshake headers.
• Verify CrossWS open, message, close, and error hooks.
• Verify text, binary, and plain-object sending.
• Verify message conversion helpers.
• Verify close() and terminate().
• Verify route-wide topic subscription, publication, and pathname namespace isolation.
• Verify hook exceptions and rejected promises close with 1011.
• Verify disconnect before handler completion.
• Verify rewrites, dynamic routes, base paths, and proxy.ts.
• Verify HMR WebSockets remain unaffected.
• Verify graceful shutdown.
• Verify static export and Edge runtime errors.
• Add an Adapter fixture invoking upgradeHandler.
• Verify an unsupported Adapter can force experimental.webSocketRouteHandlers off through modifyConfig in development and production.
• Verify the defensive 501 response when an upgrade handler lacks raw Node.js primitives.

References

• Deployment Adapters RFC
• NextResponse documentation
• Node.js HTTP upgrade event
• CrossWS Node adapter
• CrossWS hooks
• CrossWS peer API
• CrossWS message API

[jasperaelvoet]

I think a separate websocket.ts file would make more sense, especially for Vercel Functions where you normally think of route handlers as short-lived request/response code. WebSockets have a different mental model since the connection lives longer and can have per-connection state.

[yakubka]

Good RFC. A few implementation questions worth considering before moving to experimental.

On the upgrade handshake: the proposed NextResponse.upgrade() approach hides what happens at the HTTP level. The RFC should specify whether Next.js will handle the 101 Switching Protocols response and the Upgrade: websocket header automatically, or whether the handler author is responsible. Vercel infrastructure currently terminates WebSocket connections at the edge, so the behavior on self-hosted deployments and on Vercel should be documented separately.

On authentication: the example shows calling isAuthorized(request) before the upgrade. Once the handshake succeeds, the original request object is no longer accessible inside open/message/close. The RFC should show how to pass auth context (e.g. user id from JWT) into the peer lifecycle callbacks, otherwise developers will re-parse cookies on every message.

On the peer abstraction: peer.send() accepting an object and auto-serializing to JSON is a useful default, but the RFC needs to specify what happens when a non-serializable value is passed and whether binary frames are supported.

On deployment: WebSocket connections on serverless functions need to be backed by a persistent compute layer. The RFC should clarify how long a connection can live, what happens when the function instance is recycled, and whether this targets edge or Node.js runtime only.

The NextResponse.upgrade() API surface looks clean. The main gap is specifying the operational constraints so developers can decide whether to use this or an external WebSocket service.

[yakubka]

The CrossWS approach here is a solid foundation. A few thoughts on the draft.

The handler-executes-once-per-handshake model is the right call. It keeps the authentication and request-processing pattern consistent with regular route handlers, so developers can apply cookies, headers, and early returns without learning a separate API.

One thing worth clarifying in the RFC is the lifecycle for cookies set on the upgrade response. Standard WebSocket handshakes do send a Set-Cookie in the 101 response, but many proxies and clients strip or ignore it. The example sets cookies.set on the upgrade response, which raises the question of whether those cookies will reliably reach the browser. Calling this out explicitly in the spec would save a lot of confusion for developers who discover the cookies are not persisting in production.

On the peer ID in the x-connection-id header: the 101 response headers are not accessible to the browser via the WebSocket API (the browser WebSocket constructor gives no access to handshake response headers). If the connection ID is needed by the client, the pattern would be to send it as the first message in the open hook rather than as a header. Worth noting in the docs or examples.

The scope limitation around adapters is important. The adapter section should make clear that NextResponse.upgrade() on platforms that do not support the raw upgrade primitive will need to fall back gracefully rather than hanging. A clear error at dev time would help.

The experimental flag makes sense here. The main compatibility risk is Vercel deployment, since their edge network typically terminates WebSocket connections at the load balancer. The RFC should state whether NextResponse.upgrade() is expected to work on Vercel or only on self-hosted Node.js.

[ahmedmbarektorjmene]

yeah this should work only on self hosted nextjs.