feat: native support for Websockets

documentation/docs/25-build-and-deploy/99-writing-adapters.md

@@ -58,3 +58,5 @@ Within the `adapt` method, there are a number of things that an adapter should d
 - Put the user's static files and the generated JS/CSS in the correct location for the target platform
 
 Where possible, we recommend putting the adapter output under the `build/` directory with any intermediate output placed under `.svelte-kit/[adapter-name]`.
+
+To add WebSockets to a SvelteKit adapter, you will need to handle upgrading the connection within the adapter. The crossws [adapter integration guides](https://crossws.unjs.io/adapters) may be a helpful reference.

documentation/docs/30-advanced/15-websockets.md

@@ -0,0 +1,126 @@
+---
+title: WebSockets
+---
+
+## The `socket` object
+
+[WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) provide a way to open a bidirectional communication channel between the client and server.
+
+SvelteKit accepts a `socket` object in `+server.js` files that you can use to handle WebSocket connections to different routes in your app.
+
+The shape of this socket object directly corresponds to the [Hooks](https://crossws.unjs.io/guide/hooks) type in `crossws` as this is the package being used to handle cross-platform WebSocket connections.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	upgrade(req) {
+        // ...
+	},
+
+	open(peer) {
+        // ...
+	},
+
+	message(peer, message) {
+        // ...
+	},
+
+	close(peer, event) {
+		// ...
+	},
+
+	error(peer, error) {
+		// ...
+	}
+};
+```
+
+### Upgrade
+
+The `upgrade` hook is called when a WebSocket connection is established, and can be used to accept or reject the connection attempt.
+
+Additionally, SvelteKit provides a WebSocket specific `accept` helper function alongside the existing `error` function used for HTTP errors to easily accept or reject connections.
+
+```js
+import { error, accept } from "@sveltejs/kit";
+
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	upgrade(req) {
+		// Accept the WebSocket connection with a return
+		return accept();
+
+		// Reject the WebSocket connection with a standard SvelteKit error
+		error(401, 'unauthorized');
+	}
+
+    // ...
+};
+```
+
+### Open
+
+The `open` hook is called when a WebSocket connection is opened. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object as a parameter.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	open(peer) {
+		// ...
+	}
+};
+```
+
+### Message
+
+The `message` hook is called when a message is received from the client. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object and the [message](https://crossws.unjs.io/guide/message) as parameters.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	message(peer, message) {
+		// ...
+	}
+};
+```
+
+### Close
+
+The `close` hook is called when a WebSocket connection is closed. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object and the close event as parameters.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	close(peer, event) {
+		// ...
+	}
+};
+```
+
+### Error
+
+The `error` hook is called when a WebSocket connection error occurs. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object and the error as parameters.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	error(peer, error) {
+		// ...
+	}
+};
+```
+
+## Connecting from the client
+
+To connect to a WebSocket endpoint in SvelteKit, you can use the native `WebSocket` class in the browser.
+
+```js
+// To connect to src/routes/ws/+server.js
+const socket = new WebSocket(`/ws`);
+```
+
+See [the WebSocket documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket) for more details.
+
+## Compatibility
+
+SvelteKit uses [`unjs/crossws`](https://crossws.unjs.io) to handle WebSocket connections. Please refer to their [compatibility table](https://crossws.unjs.io/guide/peer#compatibility) for the peer object in different runtime environments.

packages/adapter-auto/package.json

@@ -42,7 +42,7 @@
 	"devDependencies": {
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"typescript": "^5.3.3",
 		"vitest": "^3.0.1"
 	},

packages/adapter-cloudflare-workers/files/entry.js

@@ -2,6 +2,8 @@ import { Server } from 'SERVER';
 import { manifest, prerendered, base_path } from 'MANIFEST';
 import { getAssetFromKV, mapRequestToAsset } from '@cloudflare/kv-asset-handler';
 import static_asset_manifest_json from '__STATIC_CONTENT_MANIFEST';
+import crossws from 'crossws/adapters/cloudflare';
+
 const static_asset_manifest = JSON.parse(static_asset_manifest_json);
 
 const server = new Server(manifest);
@@ -20,6 +22,15 @@ export default {
 	async fetch(req, env, context) {
 		await server.init({ env });
 
+		const ws = crossws({
+			resolve: server.resolve()
+		});
+
+		if (req.headers.get('upgrade') === 'websocket') {
+			// @ts-ignore wtf is Cloudflare doing to these types
+			return ws.handleUpgrade(req, env, context);
+		}
+
 		const url = new URL(req.url);
 
 		// static assets

packages/adapter-cloudflare-workers/package.json

@@ -38,14 +38,15 @@
 		"check": "tsc --skipLibCheck"
 	},
 	"dependencies": {
-		"@cloudflare/workers-types": "^4.20231121.0",
+		"@cloudflare/workers-types": "^4.20250129.0",
 		"@iarna/toml": "^2.2.5",
+		"crossws": "^0.3.3",
 		"esbuild": "^0.24.0"
 	},
 	"devDependencies": {
 		"@cloudflare/kv-asset-handler": "^0.3.0",
 		"@sveltejs/kit": "workspace:^",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"typescript": "^5.3.3"
 	},
 	"peerDependencies": {

packages/adapter-cloudflare/package.json

@@ -41,12 +41,13 @@
 	},
 	"dependencies": {
 		"@cloudflare/workers-types": "^4.20241106.0",
+		"crossws": "^0.3.3",
 		"esbuild": "^0.24.0",
 		"worktop": "0.8.0-next.18"
 	},
 	"devDependencies": {
 		"@sveltejs/kit": "workspace:^",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"@types/ws": "^8.5.10",
 		"typescript": "^5.3.3"
 	},

packages/adapter-cloudflare/src/worker.js

@@ -1,6 +1,7 @@
 import { Server } from 'SERVER';
 import { manifest, prerendered, base_path } from 'MANIFEST';
 import * as Cache from 'worktop/cfw.cache';
+import crossws from 'crossws/adapters/cloudflare';
 
 const server = new Server(manifest);
 
@@ -11,9 +12,20 @@ const version_file = `${app_path}/version.json`;
 
 /** @type {import('worktop/cfw').Module.Worker<{ ASSETS: import('worktop/cfw.durable').Durable.Object }>} */
 const worker = {
+	// @ts-ignore wtf is Cloudflare doing to these types
 	async fetch(req, env, context) {
 		// @ts-ignore
 		await server.init({ env });
+
+		const ws = crossws({
+			resolve: server.resolve()
+		});
+
+		if (req.headers.get('upgrade') === 'websocket') {
+			// @ts-ignore wtf is Cloudflare doing to these types
+			return ws.handleUpgrade(req, env, context);
+		}
+
 		// skip cache if "cache-control: no-cache" in request
 		let pragma = req.headers.get('cache-control') || '';
 		let res = !pragma.includes('no-cache') && (await Cache.lookup(req));

packages/adapter-netlify/package.json

@@ -52,7 +52,7 @@
 		"@rollup/plugin-node-resolve": "^16.0.0",
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"@types/set-cookie-parser": "^2.4.7",
 		"rollup": "^4.14.2",
 		"typescript": "^5.3.3",

packages/adapter-node/internal.d.ts

@@ -4,6 +4,7 @@ declare module 'ENV' {
 
 declare module 'HANDLER' {
 	export const handler: import('polka').Middleware;
+	export const resolve: import('crossws').ResolveHooks;
 }
 
 declare module 'MANIFEST' {

packages/adapter-node/package.json

@@ -45,7 +45,8 @@
 		"@polka/url": "^1.0.0-next.28",
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
+		"crossws": "^0.3.3",
 		"polka": "^1.0.0-next.28",
 		"sirv": "^3.0.0",
 		"typescript": "^5.3.3",

packages/adapter-node/src/handler.js

@@ -212,3 +212,5 @@ export const handler = sequence(
 		ssr
 	].filter(Boolean)
 );
+
+export const resolve = server.resolve;

packages/adapter-node/src/index.js

@@ -1,7 +1,8 @@
 import process from 'node:process';
-import { handler } from 'HANDLER';
+import { handler, resolve } from 'HANDLER';
 import { env } from 'ENV';
 import polka from 'polka';
+import crossws from 'crossws/adapters/node';
 
 export const path = env('SOCKET_PATH', false);
 export const host = env('HOST', '0.0.0.0');
@@ -33,6 +34,12 @@ let idle_timeout_id;
 
 const server = polka().use(handler);
 
+const ws = crossws({
+	resolve
+});
+
+server.server.on('upgrade', ws.handleUpgrade);
+
 if (socket_activation) {
 	server.listen({ fd: SD_LISTEN_FDS_START }, () => {
 		console.log(`Listening on file descriptor ${SD_LISTEN_FDS_START}`);

packages/adapter-static/package.json

@@ -42,7 +42,7 @@
 		"@playwright/test": "^1.44.1",
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"sirv": "^3.0.0",
 		"svelte": "^5.2.9",
 		"typescript": "^5.3.3",

packages/adapter-vercel/package.json

@@ -46,7 +46,7 @@
 	"devDependencies": {
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"typescript": "^5.3.3",
 		"vitest": "^3.0.1"
 	},

packages/enhanced-img/package.json

@@ -44,10 +44,10 @@
 	},
 	"devDependencies": {
 		"@types/estree": "^1.0.5",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"rollup": "^4.27.4",
 		"svelte": "^5.2.9",
-		"typescript": "^5.6.3",
+		"typescript": "^5.3.3",
 		"vite": "^6.0.11",
 		"vitest": "^3.0.1"
 	},

packages/kit/package.json

@@ -20,6 +20,7 @@
 	"dependencies": {
 		"@types/cookie": "^0.6.0",
 		"cookie": "^0.6.0",
+		"crossws": "^0.3.3",
 		"devalue": "^5.1.0",
 		"esm-env": "^1.2.2",
 		"import-meta-resolve": "^4.1.0",
@@ -34,7 +35,7 @@
 		"@playwright/test": "^1.44.1",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
 		"@types/connect": "^3.4.38",
-		"@types/node": "^18.19.48",
+		"@types/node": "^20.17.16",
 		"@types/set-cookie-parser": "^2.4.7",
 		"dts-buddy": "^0.5.4",
 		"rollup": "^4.14.2",

packages/kit/src/exports/index.js

@@ -110,6 +110,18 @@ export function redirect(status, location) {
 	);
 }
 
+const acceptResponse = new Response(null, {
+	status: 200
+});
+
+/**
+ * Accepts a WebSocket upgrade request. When called during request handling, SvelteKit will accept the WebSocket upgrade request.
+ * @return {Response} This response instructs SvelteKit to accept the WebSocket upgrade request.
+ */
+export function accept() {
+	return acceptResponse;
+}
+
 /**
  * Checks whether this is a redirect thrown by {@link redirect}.
  * @param {unknown} e The object to check.

packages/kit/src/exports/public.d.ts

@@ -1277,6 +1277,7 @@ export class Server {
 	constructor(manifest: SSRManifest);
 	init(options: ServerInitOptions): Promise<void>;
 	respond(request: Request, options: RequestOptions): Promise<Response>;
+	resolve(): import('crossws').ResolveHooks;
 }
 
 export interface ServerInitOptions {
@@ -1464,6 +1465,12 @@ export type SubmitFunction<
 	  }) => void)
 >;
 
+/**
+ * Shape of the `export const socket = {..}` object in `+server.js`.
+ * See [WebSockets](https://svelte.dev/docs/kit/websockets) for more information.
+ */
+export type Socket = import('crossws').Hooks;
+
 /**
  * The type of `export const snapshot` exported from a page or layout component.
  */