feat: native support for Websockets

documentation/docs/25-build-and-deploy/40-adapter-node.md

@@ -241,12 +241,12 @@ WantedBy=sockets.target
 
 The adapter creates two files in your build directory — `index.js` and `handler.js`. Running `index.js` — e.g. `node build`, if you use the default build directory — will start a server on the configured port.
 
-Alternatively, you can import the `handler.js` file, which exports a handler suitable for use with [Express](https://github.com/expressjs/express), [Connect](https://github.com/senchalabs/connect) or [Polka](https://github.com/lukeed/polka) (or even just the built-in [`http.createServer`](https://nodejs.org/dist/latest/docs/api/http.html#httpcreateserveroptions-requestlistener)) and set up your own server:
+Alternatively, you can import the `handler.js` file, which exports handlers suitable for use with [Express](https://github.com/expressjs/express), [Connect](https://github.com/senchalabs/connect) or [Polka](https://github.com/lukeed/polka) (or even just the built-in [`http.createServer`](https://nodejs.org/dist/latest/docs/api/http.html#httpcreateserveroptions-requestlistener)) and set up your own server:
 
 ```js
 // @errors: 2307 7006
 /// file: my-server.js
-import { handler } from './build/handler.js';
+import { handler, upgradeHandler } from './build/handler.js';
 import express from 'express';
 
 const app = express();
@@ -256,10 +256,13 @@ app.get('/healthcheck', (req, res) => {
 	res.end('ok');
 });
 
-// let SvelteKit handle everything else, including serving prerendered pages and static assets
+// let SvelteKit handle serving prerendered pages, static assets, and SSR
 app.use(handler);
 
-app.listen(3000, () => {
+const server = app.listen(3000, () => {
 	console.log('listening on port 3000');
 });
+
+// let SvelteKit handle protocol upgrades for WebSocket connections
+server.on('upgrade', upgradeHandler);
 ```

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,133 @@
+---
+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 a client and a server.
+
+A `+server.js` file can export a `socket` object to handle WebSocket connections. It uses [crossws](https://crossws.unjs.io/) to provide a consistent interface across different platforms. You can define [hooks](https://crossws.unjs.io/guide/hooks), all optional, to handle the different stages of the WebSocket lifecycle.
+
+```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 before a WebSocket connection is established. It receives the [request](https://developer.mozilla.org/docs/Web/API/Request) object as a parameter.
+
+You can use the [`error`](@sveltejs-kit#error) function imported from `@sveltejs/kit` to easily reject connections. Requests will be auto-accepted if the `upgrade` hook is not defined or does not `error`.
+
+```js
+import { error } from "@sveltejs/kit";
+
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	upgrade(request) {
+		if (request.headers.get('origin') !== 'allowed_origin') {
+			// Reject the WebSocket connection by throwing an error
+			error(403, 'Forbidden');
+		}
+	}
+};
+```
+
+### open
+
+The `open` hook is called when a WebSocket connection is opened. It receives the [peer](https://crossws.unjs.io/guide/peer) object, to allow interacting with connected clients, 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) object, to allow interacting with connected clients, and the [message](https://crossws.unjs.io/guide/message) object, containing data from the client, 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) object, to allow interacting with connected clients, and the close event object, containing the [WebSocket connection close code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code#value) and reason, 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) object, to allow interacting with connected clients, 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, you can use the [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket) constructor in the browser.
+
+```svelte
+<script>
+	import { onMount } from 'svelte';
+
+	onMount(() => {
+		// To connect to src/routes/ws/+server.js
+		const socket = new WebSocket(`/ws`);
+
+		socket.addEventListener("open", (event) => {
+			socket.send("Hello Server!");
+		});
+
+		// ...
+	});
+</script>
+```
+
+See [the WebSocket documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) for more details.
+
+## Compatibility
+
+SvelteKit uses [`crossws`](https://crossws.unjs.io) to handle cross-platform 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,8 +42,8 @@
 	"devDependencies": {
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
-		"@types/node": "^18.19.48",
-		"typescript": "^5.3.3",
+		"@types/node": "^20.17.16",
+		"typescript": "^5.5.3",
 		"vitest": "^3.0.1"
 	},
 	"dependencies": {

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

@@ -2,6 +2,9 @@ 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';
+// TODO: allow WebSocket integration with Durable Objects using crossws/adapters/cloudflare-durable
+import crossws from 'crossws/adapters/cloudflare';
+
 const static_asset_manifest = JSON.parse(static_asset_manifest_json);
 
 const server = new Server(manifest);
@@ -11,15 +14,48 @@ const app_path = `/${manifest.appPath}`;
 const immutable = `${app_path}/immutable/`;
 const version_file = `${app_path}/version.json`;
 
+/** @type {import('crossws').ResolveHooks | undefined} */
+let resolve_websocket_hooks = undefined;
+const ws = crossws({
+	resolve: (req) => resolve_websocket_hooks?.(req) ?? {}
+});
+
 export default {
 	/**
 	 * @param {Request} req
 	 * @param {any} env
 	 * @param {any} context
 	 */
 	async fetch(req, env, context) {
+		const options = {
+			platform: {
+				env,
+				context,
+				// lib.dom is interfering with workers-types
+				caches,
+				// req is actually a Cloudflare request not a standard request
+				cf: req.cf
+			},
+			getClientAddress() {
+				return req.headers.get('cf-connecting-ip');
+			}
+		};
+
 		await server.init({ env });
 
+		if (req.headers.get('upgrade') === 'websocket') {
+			resolve_websocket_hooks = server.resolveWebSocketHooks(
+				// @ts-ignore
+				options
+			);
+			return ws.handleUpgrade(
+				// @ts-ignore wtf is Cloudflare doing to these types
+				req,
+				env,
+				context
+			);
+		}
+
 		const url = new URL(req.url);
 
 		// static assets
@@ -90,19 +126,11 @@ export default {
 		}
 
 		// dynamically-generated pages
-		return await server.respond(req, {
-			platform: {
-				env,
-				context,
-				// @ts-expect-error lib.dom is interfering with workers-types
-				caches,
-				// @ts-expect-error req is actually a Cloudflare request not a standard request
-				cf: req.cf
-			},
-			getClientAddress() {
-				return req.headers.get('cf-connecting-ip');
-			}
-		});
+		return await server.respond(
+			req,
+			// @ts-ignore
+			options
+		);
 	}
 };
 

packages/adapter-cloudflare-workers/package.json

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

packages/adapter-cloudflare/package.json

@@ -41,14 +41,15 @@
 	},
 	"dependencies": {
 		"@cloudflare/workers-types": "^4.20241106.0",
+		"crossws": "^0.3.4",
 		"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"
+		"typescript": "^5.5.3"
 	},
 	"peerDependencies": {
 		"@sveltejs/kit": "^2.0.0",

packages/adapter-cloudflare/src/worker.js

@@ -1,6 +1,8 @@
 import { Server } from 'SERVER';
 import { manifest, prerendered, base_path } from 'MANIFEST';
 import * as Cache from 'worktop/cfw.cache';
+// TODO: allow WebSocket integration with Durable Objects using crossws/adapters/cloudflare-durable?
+import crossws from 'crossws/adapters/cloudflare';
 
 const server = new Server(manifest);
 
@@ -9,11 +11,39 @@ const app_path = `/${manifest.appPath}`;
 const immutable = `${app_path}/immutable/`;
 const version_file = `${app_path}/version.json`;
 
+/** @type {import('crossws').ResolveHooks | undefined} */
+let resolve_websocket_hooks = undefined;
+const ws = crossws({
+	resolve: (req) => resolve_websocket_hooks?.(req) ?? {}
+});
+
 /** @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) {
+		const options = {
+			platform: { env, context, caches, cf: req.cf },
+			getClientAddress() {
+				return req.headers.get('cf-connecting-ip');
+			}
+		};
+
 		// @ts-ignore
 		await server.init({ env });
+
+		if (req.headers.get('upgrade') === 'websocket') {
+			resolve_websocket_hooks = server.resolveWebSocketHooks(
+				// @ts-ignore
+				options
+			);
+			return ws.handleUpgrade(
+				// @ts-ignore wtf is Cloudflare doing to these types
+				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));
@@ -58,13 +88,11 @@ const worker = {
 			});
 		} else {
 			// dynamically-generated pages
-			res = await server.respond(req, {
+			res = await server.respond(
+				req,
 				// @ts-ignore
-				platform: { env, context, caches, cf: req.cf },
-				getClientAddress() {
-					return req.headers.get('cf-connecting-ip');
-				}
-			});
+				options
+			);
 		}
 
 		// write to `Cache` only if response is not an error,

packages/adapter-netlify/package.json

@@ -52,10 +52,10 @@
 		"@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",
+		"typescript": "^5.5.3",
 		"vitest": "^3.0.1"
 	},
 	"peerDependencies": {

packages/adapter-node/internal.d.ts

@@ -4,6 +4,7 @@ declare module 'ENV' {
 
 declare module 'HANDLER' {
 	export const handler: import('polka').Middleware;
+	export const upgradeHandler: import('crossws/adapters/node').NodeAdapter['handleUpgrade'];
 }
 
 declare module 'MANIFEST' {