feat: custom server entry points during development

.changeset/custom-server-handler.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: allow adapters to provide a `customHandler` that handles requests to the server

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

@@ -40,6 +40,8 @@ export default function (options) {
 				// Return `false if it can't, or throw a descriptive error.
 			}
 		},
+		// Specify the path of a module to customise request handling
+		customHandler: import.meta.resolve('./handler.js'),
 		vite: {
 			plugins: [
 				// add plugins here to integrate with Vite
@@ -51,7 +53,7 @@ export default function (options) {
 }
 ```
 
-Of these, `name` and `adapt` are required. `emulate`, `vite.plugins` and `supports` are optional.
+Of these, `name` and `adapt` are required. `emulate`, `customHandler`, `vite.plugins` and `supports` are optional.
 
 Within the `adapt` method, there are a number of things that an adapter should do:
 
@@ -66,3 +68,53 @@ 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]`.
+
+## Custom request handler
+
+You can customise your server's initialisation and request handling by adding a `customHandler` property resolved to the path of your handler file.
+
+```js
+// @errors: 2322
+// @filename: ambient.d.ts
+type AdapterSpecificOptions = any;
+
+// @filename: index.js
+// ---cut---
+/** @param {AdapterSpecificOptions} options */
+export default function (options) {
+	/** @type {import('@sveltejs/kit').Adapter} */
+	const adapter = {
+		name: 'adapter-package-name',
+		async adapt(builder) {
+			// adapter implementation
+		},
+		+++customHandler: import.meta.resolve('./src/handler.js')+++
+	}
+
+	return adapter;
+};
+```
+
+The handler file should export a default function that returns a request handler. The should return a `Response` such as by calling `server.respond` along with any [platform-specific context](types#Platform).
+
+```js
+/// file: src/handler.js
+// @errors: 2322
+/** @type {import('@sveltejs/kit').SSRHandler} */
+export default async function handler(server) {
+	// perform setup work here
+
+	return async (request) => {
+		// custom request/response handling logic goes here
+		if (new URL(request.url).pathname === '/_ping') {
+			return new Response('pong');
+		}
+
+		return await server.respond(request, {
+			platform: {
+				// the shape of `App.Platform`
+			}
+		});
+	};
+}
+```

packages/adapter-cloudflare/index.js

@@ -119,7 +119,7 @@ export default function (options = {}) {
 					// will be interpreted as escape characters and create an incorrect import path.
 					// We also need to ensure the relative imports start with ./ since Wrangler
 					// errors if a relative import looks like a package import
-					SERVER: `./${posixify(path.relative(worker_dest_dir, builder.getServerDirectory()))}/index.js`,
+					SERVER: `./${posixify(path.relative(worker_dest_dir, builder.getServerDirectory()))}/server.js`,
 					MANIFEST: `./${posixify(path.relative(worker_dest_dir, tmp))}/manifest.js`,
 					ASSETS: assets_binding
 				}

packages/adapter-netlify/index.js

@@ -123,7 +123,7 @@ function generate_serverless_functions({ builder, publish, split }) {
 	builder.writeServer('.netlify/v1/server');
 
 	const replace = {
-		'0SERVER': './server/index.js' // digit prefix prevents CJS build from using this as a variable name, which would also get replaced
+		'0SERVER': './server/server.js' // digit prefix prevents CJS build from using this as a variable name, which would also get replaced
 	};
 
 	builder.copy(files, '.netlify/v1', { replace, filter: (file) => !file.endsWith('edge.js') });
@@ -365,7 +365,7 @@ async function generate_edge_functions({ builder }) {
 
 	builder.copy(`${files}/edge.js`, `${tmp}/entry.js`, {
 		replace: {
-			'0SERVER': `${relativePath}/index.js`,
+			'0SERVER': `${relativePath}/server.js`,
 			MANIFEST: './manifest.js'
 		}
 	});

packages/adapter-node/index.js

@@ -90,7 +90,7 @@ export default function (opts = {}) {
 						// resolve the app's server and manifest, generated above
 						name: 'adapter-node-resolve-app',
 						resolveId(id) {
-							if (id === 'SERVER') return `${server}/index.js`;
+							if (id === 'SERVER') return `${server}/server.js`;
 							if (id === 'MANIFEST') return `${server}/manifest.js`;
 						}
 					},

packages/adapter-vercel/index.js

@@ -56,15 +56,15 @@ const plugin = function (defaults = {}) {
 				const dir = `${dirs.functions}/${name}.func`;
 
 				const relativePath = path.posix.relative(tmp, builder.getServerDirectory());
-				builder.copy(`${files}/serverless.js`, `${tmp}/index.js`, {
+				builder.copy(`${files}/serverless.js`, `${tmp}/server.js`, {
 					replace: {
-						SERVER: `${relativePath}/index.js`,
+						SERVER: `${relativePath}/server.js`,
 						MANIFEST: './manifest.js'
 					}
 				});
 				if (builder.hasServerInstrumentationFile()) {
 					builder.instrument({
-						entrypoint: `${tmp}/index.js`,
+						entrypoint: `${tmp}/server.js`,
 						instrumentation: `${builder.getServerDirectory()}/instrumentation.server.js`
 					});
 				}
@@ -74,7 +74,7 @@ const plugin = function (defaults = {}) {
 					`export const manifest = ${builder.generateManifest({ relativePath, routes })};\n`
 				);
 
-				await create_function_bundle(builder, `${tmp}/index.js`, dir, config);
+				await create_function_bundle(builder, `${tmp}/server.js`, dir, config);
 
 				for (const asset of builder.findServerAssets(routes)) {
 					// TODO use symlinks, once Build Output API supports doing so

packages/kit/src/core/postbuild/fallback.js

@@ -1,3 +1,4 @@
+/** @import { SSRHandler } from '@sveltejs/kit' */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -22,28 +23,44 @@ async function generate_fallback({ manifest_path, env, out_dir, origin, assets }
 	const { set_building } = await import(pathToFileURL(`${server_root}/server/internal.js`).href);
 
 	/** @type {import('types').ServerModule} */
-	const { Server } = await import(pathToFileURL(`${server_root}/server/index.js`).href);
+	const { Server } = await import(pathToFileURL(`${server_root}/server/server.js`).href);
 
 	/** @type {import('@sveltejs/kit').SSRManifest} */
 	const manifest = (await import(pathToFileURL(manifest_path).href)).manifest;
 
 	set_building();
 
 	const server = new Server(manifest);
-	await server.init({ env });
-
-	const response = await server.respond(new Request(origin + '/[fallback]'), {
-		getClientAddress: () => {
-			throw new Error('Cannot read clientAddress during prerendering');
-		},
-		prerendering: {
-			fallback: true,
-			dependencies: new Map(),
-			remote_responses: new Map()
-		},
-		read: (file) => readFileSync(join(assets, file))
+	await server.init({
+		env,
+		read: (file) => {
+			throw new Error(`Cannot call \`read\` for ${file} while prerendering a fallback page`);
+		}
 	});
 
+	/** @type {{ default: SSRHandler }} */
+	const { default: init_server } = await import(
+		pathToFileURL(`${server_root}/server/handler.js`).href
+	);
+	const respond = await init_server({
+		respond: (request, options) => {
+			return server.respond(request, {
+				...options,
+				getClientAddress: () => {
+					throw new Error('Cannot read clientAddress during prerendering');
+				},
+				prerendering: {
+					fallback: true,
+					dependencies: new Map(),
+					remote_responses: new Map()
+				},
+				read: (file) => readFileSync(join(assets, file))
+			});
+		}
+	});
+
+	const response = await respond(new Request(origin + '/[fallback]'));
+
 	if (response.ok) {
 		return await response.text();
 	}

packages/kit/src/core/postbuild/prerender.js

@@ -1,3 +1,4 @@
+/** @import { SSRHandler } from '@sveltejs/kit' */
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -56,7 +57,10 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env, vit
 	set_env(env);
 
 	/** @type {import('types').ServerModule} */
-	const { Server } = await import(pathToFileURL(`${out}/server/index.js`).href);
+	const { Server } = await import(pathToFileURL(`${out}/server/server.js`).href);
+
+	/** @type {{ default: SSRHandler }} */
+	const { default: init_server } = await import(pathToFileURL(`${out}/server/handler.js`).href);
 
 	const throw_handled = () => {
 		throw new Error('__handled__');
@@ -262,6 +266,13 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env, vit
 	/** @type {Map<string, Promise<any>>} */
 	const remote_responses = new Map();
 
+	// the custom/default handler's setup phase must run only once (per the `SSRHandler`
+	// contract), so `respond` is created a single time below. Per-visit state (the
+	// `dependencies` map) is threaded through to the shared handler via this `WeakMap`,
+	// keyed on the `Request` that flows into `server.respond`.
+	/** @type {WeakMap<Request, Map<string, import('types').PrerenderDependency>>} */
+	const dependencies_by_request = new WeakMap();
+
 	/** @type {Map<string, Set<string>>} */
 	const expected_hashlinks = new Map();
 
@@ -301,29 +312,11 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env, vit
 
 		const request = new Request(prerender_origin + encoded);
 
-		const response = await server.respond(request, {
-			getClientAddress() {
-				throw new Error('Cannot read clientAddress during prerendering');
-			},
-			prerendering: {
-				dependencies,
-				remote_responses
-			},
-			read: (file) => {
-				// stuff we just wrote
-				const filepath = saved.get(file);
-				if (filepath) return readFileSync(filepath);
-
-				// Static assets emitted during build
-				if (file.startsWith(config.appDir)) {
-					return readFileSync(`${out}/server/${file}`);
-				}
+		// thread the per-visit `dependencies` map through to the shared `respond`
+		// handler (created once, after `server.init` below)
+		dependencies_by_request.set(request, dependencies);
 
-				// stuff in `static`
-				return readFileSync(join(config.files.assets, file));
-			},
-			emulator
-		});
+		const response = await respond(request);
 
 		const encoded_id = response.headers.get('x-sveltekit-routeid');
 		const decoded_id = encoded_id && decode_uri(encoded_id);
@@ -594,6 +587,38 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env, vit
 		read: (file) => createReadableStream(`${config.outDir}/output/server/${file}`)
 	});
 
+	// create the custom/default handler once, honouring the `SSRHandler`
+	// "setup runs once" contract. Per-visit `dependencies` are looked up from
+	// `dependencies_by_request` using the `Request` passed to `server.respond`.
+	const respond = await init_server({
+		respond: (request, options) => {
+			return server.respond(request, {
+				...options,
+				getClientAddress() {
+					throw new Error('Cannot read clientAddress during prerendering');
+				},
+				prerendering: {
+					dependencies: dependencies_by_request.get(request) ?? new Map(),
+					remote_responses
+				},
+				read: (file) => {
+					// stuff we just wrote
+					const filepath = saved.get(file);
+					if (filepath) return readFileSync(filepath);
+
+					// Static assets emitted during build
+					if (file.startsWith(config.appDir)) {
+						return readFileSync(`${out}/server/${file}`);
+					}
+
+					// stuff in `static`
+					return readFileSync(join(config.files.assets, file));
+				},
+				emulator
+			});
+		}
+	});
+
 	log.info('Prerendering');
 
 	for (const entry of config.prerender.entries) {

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

@@ -71,6 +71,11 @@ export interface Adapter {
 	 * during dev, build and prerendering.
 	 */
 	emulate?: () => MaybePromise<Emulator>;
+	/**
+	 * The path to a module whose default export is a [custom handler](https://svelte.dev/docs/kit/writing-adapters#Custom-request-handler).
+	 * @since 3.0.0
+	 */
+	customHandler?: string;
 	vite?: {
 		/**
 		 * Plugins provided by the adapter are placed before any of SvelteKit's own plugins.
@@ -80,6 +85,14 @@ export interface Adapter {
 	};
 }
 
+/**
+ * The [custom handler](https://svelte.dev/docs/kit/writing-adapters#Custom-request-handler) an adapter can specify to customise request handling. It is expected to return a function which returns a `Response` or calls `server.respond` with any [platform-specific context](https://svelte.dev/docs/kit/types#Platform).
+ * @since 3.0.0
+ */
+export type SSRHandler = (server: {
+	respond: (request: Request, options?: Pick<RequestOptions, 'platform'>) => Promise<Response>;
+}) => MaybePromise<(request: Request) => MaybePromise<Response>>;
+
 export type LoadProperties<input extends Record<string, any> | void> = input extends void
 	? undefined // needs to be undefined, because void will break intellisense
 	: input extends Record<string, any>