Websocket support in tanstack start

[briansunter]

What’s the best approach to integrate websocket support in tanstack start that aligns with future direction given the recent changes?

https://nize.ph/posts/tanstack-start-websockets/

[essential-randomness]

Same question here. I've just spent some time trying to get this to work and couldn't get to. I cannot find much around websockets on the documentation of any part of the stack either.

[dotnize]

https://discord.com/channels/719702312431386674/1382130510402162698

#3777 (reply in thread)

probably this when it's out. this should make implementing websockets even more flexible. i'll get around to updating my guide when I have the time

[redhat127]

how do you implement webscoket in a tanstack start app right now?

[carry0987]

I have same question

[dotnize]

For Cloudflare users, I just published a new guide that uses Durable Objects:

https://nize.ph/tanstack-start-websockets-cloudflare/

Demo: https://ts-cf-websockets.mugnavo.com/
Repo: https://github.com/dotnize/tanstack-websockets-cloudflare

[fguitton]

Hi,

It is possible to rely on the default Nitro server, albeit in a rather "inelegant" fashion.
You can setup a WebSocket route as follows:

In your vite.config.ts add the following to the Nitro plugin options

{
    // ...,
    plugins: [
        devtools(),
        nitro({
            // ...,
            serverDir: "<serverDir>",
            features: {
                websocket: true,
            }
        }),
        // ...
    ]
}

In the <serverDir>/routes you have referenced, create your route files as you would otherwise in TanStack.
The <serverDir> is adhoc to the existing default ./src/routes, do not overlap them, for example define it at ./src/websocket.
This is supported by H3 and its underlying crossws peer implementation.
For example you can create <serverDir>/routes/message.ts:

import { defineWebSocketHandler } from "nitro/h3";

export default defineWebSocketHandler({
    open(peer) {
        peer.send({ id: peer.id, message: "server hello" });
        peer.publish("channel", { id: peer.id, status: "joined" });
        peer.subscribe("channel");
    },
    message(peer, message) {
        if (message.text().includes("ping")) {
            peer.send({ id: "server", status: "pong" });
        }
    },
    close(peer) {
        peer.publish("channel", { id: peer.id, status: "left" });
    },
});

With that you will have fully functional WebSockets, directly working alongside your TanStack Start routes.
In this case it will be available at:

new WebSocket("ws://<address>/message");

Because the existing Nitro presets are not exposing the WebSocket server instance you will want to create your own, or be creative with your communication bus. (i.e. extract the peers list from the peer pointer in the event handler hooks.

I hope this helps while we wait for an more supported solution.

Best to all !
🎈

[billy-le]

Thank you! This worked perfectly.

[Andresuito]

You explained it perfectly, I use it exactly the same way!

[carry0987]

What is the current best practice for adding WebSocket support to TanStack Start (v1.163)?

I've been researching this thoroughly and hit several dead ends. Here's what I found:

What no longer works

• TanStack Start now uses srvx + h3 v2 (not Vinxi/Nitro), so older approaches like nize.ph's guide or fguitton's Nitro server routes no longer apply.
• h3 v2 exports defineWebSocketHandler which attaches crossws hooks via a .crossws property on the response, but srvx 0.11.x doesn't handle this property — so the WebSocket upgrade never actually happens.
• srvx's own docs show a crossws plugin example, but the installed version (0.11.8) has no WebSocket/crossws integration — ServerPlugin is just (server: Server) => void with no upgrade mechanism.
• @tanstack/react-start/server doesn't re-export any WebSocket-related APIs.

How TanStack Start uses srvx (the core issue)

After digging into the source, I found that TanStack Start doesn't actually expose srvx's server configuration:

Mode	How it works	Can inject srvx plugins?
Dev	Attaches a Connect middleware to Vite's dev server, only calls .fetch() on the server entry	❌
Preview	Same — Vite preview middleware, only calls .fetch()	❌
Production	srvx CLI spreads the server entry's default export into srvxServe()	⚠️ Theoretically yes, but srvx 0.11 has no WS support anyway

So even if srvx adds WebSocket support in a future version, TanStack Start's dev/preview modes would need to be updated to pass through those options.

My use case

I need a persistent bidirectional connection for real-time chat/notifications on the same host/port as my TanStack Start app.

For now I'm planning to use SSE (ReadableStream + Response) for server → client push and Server Actions for client → server writes. This works today with zero extra dependencies, but a proper WebSocket solution would be much more suitable for bidirectional real-time communication.

Questions

1. Is there a plan to integrate crossws/WebSocket support into the srvx version used by TanStack Start?
2. Is there a way to access the underlying Node.js http.Server instance from srvx to manually attach an upgrade listener?
3. Is the work mentioned in discussion #3777 still planned?
4. If WebSocket is not on the near-term roadmap, is SSE the officially recommended workaround?

Environment: TanStack Start v1.163.2, srvx 0.11.8, h3 2.0.1-rc.14. Thanks!

[Andresuito]

@schiller-manuel #3777 still planned?

[schiller-manuel]

custom server support is available since quite some time

[judaemon]

For now I'm planning to use SSE (ReadableStream + Response) for server → client push and Server Actions for client → server writes

Could you share your setup for this? I'm also trying to implement something similar using Bun + Nitro. My current blocker is that the SSE connection closes after about 10 seconds of inactivity. I'm trying to figure out the proper way to keep the connection alive or prevent it from closing.

[TheComputerM]

I had to use websockets for my usecase so after bashing my brains for a long time, I found a workaround.

1. Add VITE_USE_NITRO=true to your dev server

"scripts": {
    "dev": "VITE_USE_NITRO=true vite dev",

2. Add enable websockets in nitro

nitro({ serverDir: false, features: {websocket: true}}),

2. Add your websocket route

import { createFileRoute } from "@tanstack/react-router";
import { defineHooks } from "crossws";

const hooks = defineHooks({
	open: console.log
});

export const Route = createFileRoute("/api/machine/")({
	server: {
		handlers: {
			GET: async () => {
				return Object.assign(
					new Response("WebSocket upgrade is required.", {
						status: 426,
					}),
					{
						crossws: hooks,
					},
				);
			},
		},
	},
});