feat: server side route resolution

.changeset/nine-camels-begin.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/adapter-vercel': minor
+---
+
+feat: generate edge function dedicated to server side route resolution when using that option in SvelteKit

.changeset/slimy-foxes-travel.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: support server-side route resolution

.github/workflows/ci.yml

@@ -145,6 +145,40 @@ jobs:
           retention-days: 3
           name: test-failure-cross-platform-${{ matrix.mode }}-${{ github.run_id }}-${{ matrix.os }}-${{ matrix.node-version }}-${{ matrix.e2e-browser }}
           path: test-results-cross-platform-${{ matrix.mode }}.tar.gz
+  test-kit-server-side-route-resolution:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - mode: 'dev'
+          - mode: 'build'
+    steps:
+      - run: git config --global core.autocrlf false
+      - uses: actions/checkout@v4
+      - uses: pnpm/[email protected]
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm playwright install chromium
+      - run: pnpm run sync-all
+      - run: pnpm test:server-side-route-resolution:${{ matrix.mode }}
+      - name: Print flaky test report
+        run: node scripts/print-flaky-test-report.js
+      - name: Archive test results
+        if: failure()
+        shell: bash
+        run: find packages -type d -name test-results -not -empty | tar -czf test-results-server-side-route-resolution-${{ matrix.mode }}.tar.gz --files-from=-
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          retention-days: 3
+          name: test-failure-server-side-route-resolution-${{ matrix.mode }}-${{ github.run_id }}
+          path: test-results-server-side-route-resolution-${{ matrix.mode }}.tar.gz
   test-others:
     runs-on: ubuntu-latest
     steps:

package.json

@@ -8,6 +8,8 @@
 		"test:kit": "pnpm run --dir packages/kit test",
 		"test:cross-platform:dev": "pnpm run --dir packages/kit test:cross-platform:dev",
 		"test:cross-platform:build": "pnpm run --dir packages/kit test:cross-platform:build",
+		"test:server-side-route-resolution:dev": "pnpm run --dir packages/kit test:server-side-route-resolution:dev",
+		"test:server-side-route-resolution:build": "pnpm run --dir packages/kit test:server-side-route-resolution:build",
 		"test:vite-ecosystem-ci": "pnpm test --dir packages/kit",
 		"test:others": "pnpm test -r --filter=./packages/* --filter=!./packages/kit/ --workspace-concurrency=1",
 		"check": "pnpm -r prepublishOnly && pnpm -r check",

packages/adapter-vercel/index.js

@@ -390,6 +390,26 @@ const plugin = function (defaults = {}) {
 				);
 			}
 
+			// optional chaining to support older versions that don't have this setting yet
+			if (builder.config.kit.router?.resolution === 'server') {
+				// Create a separate edge function just for server-side route resolution.
+				// By omitting all routes we're ensuring it's small (the routes will still be available
+				// to the route resolution, becaue it does not rely on the server routing manifest)
+				await generate_edge_function(
+					`${builder.config.kit.appDir}/routes`,
+					{
+						external: 'external' in defaults ? defaults.external : undefined,
+						runtime: 'edge'
+					},
+					[]
+				);
+
+				static_config.routes.push({
+					src: `${builder.config.kit.paths.base}/${builder.config.kit.appDir}/routes(\\.js|/.*)`,
+					dest: `${builder.config.kit.paths.base}/${builder.config.kit.appDir}/routes`
+				});
+			}
+
 			// Catch-all route must come at the end, otherwise it will swallow all other routes,
 			// including ISR aliases if there is only one function
 			static_config.routes.push({ src: '/.*', dest: `/${DEFAULT_FUNCTION_NAME}` });

packages/kit/kit.vitest.config.js

@@ -1,3 +1,4 @@
+import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vitest/config';
 
 // this file needs a custom name so that the numerous test subprojects don't all pick it up
@@ -8,6 +9,9 @@ export default defineConfig({
 		}
 	},
 	test: {
+		alias: {
+			'__sveltekit/paths': fileURLToPath(new URL('./test/mocks/path.js', import.meta.url))
+		},
 		// shave a couple seconds off the tests
 		isolate: false,
 		poolOptions: {

packages/kit/package.json

@@ -69,6 +69,8 @@
 		"test:integration": "pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test",
 		"test:cross-platform:dev": "pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test:cross-platform:dev",
 		"test:cross-platform:build": "pnpm test:unit && pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test:cross-platform:build",
+		"test:server-side-route-resolution:dev": "pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test:server-side-route-resolution:dev",
+		"test:server-side-route-resolution:build": "pnpm test:unit && pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test:server-side-route-resolution:build",
 		"test:unit": "vitest --config kit.vitest.config.js run",
 		"prepublishOnly": "pnpm generate:types",
 		"generate:version": "node scripts/generate-version.js",

packages/kit/src/core/config/index.js

@@ -115,5 +115,20 @@ export function validate_config(config) {
 		);
 	}
 
-	return options(config, 'config');
+	const validated = options(config, 'config');
+
+	if (validated.kit.router.resolution === 'server') {
+		if (validated.kit.router.type === 'hash') {
+			throw new Error(
+				"The `router.resolution` option cannot be 'server' if `router.type` is 'hash'"
+			);
+		}
+		if (validated.kit.output.bundleStrategy !== 'split') {
+			throw new Error(
+				"The `router.resolution` option cannot be 'server' if `output.bundleStrategy` is 'inline' or 'single'"
+			);
+		}
+	}
+
+	return validated;
 }

packages/kit/src/core/config/index.spec.js

@@ -95,7 +95,8 @@ const get_defaults = (prefix = '') => ({
 		output: { preloadStrategy: 'modulepreload', bundleStrategy: 'split' },
 		outDir: join(prefix, '.svelte-kit'),
 		router: {
-			type: 'pathname'
+			type: 'pathname',
+			resolution: 'client'
 		},
 		serviceWorker: {
 			register: true

packages/kit/src/core/config/options.js

@@ -261,7 +261,8 @@ const options = object(
 			}),
 
 			router: object({
-				type: list(['pathname', 'hash'])
+				type: list(['pathname', 'hash']),
+				resolution: list(['client', 'server'])
 			}),
 
 			serviceWorker: object({

packages/kit/src/core/generate_manifest/index.js

@@ -8,6 +8,7 @@ import { compact } from '../../utils/array.js';
 import { join_relative } from '../../utils/filesystem.js';
 import { dedent } from '../sync/utils.js';
 import { find_server_assets } from './find_server_assets.js';
+import { uneval } from 'devalue';
 
 /**
  * Generates the data used to write the server-side manifest.js file. This data is used in the Vite
@@ -25,10 +26,12 @@ export function generate_manifest({ build_data, relative_path, routes }) {
 	const reindexed = new Map();
 	/**
 	 * All nodes actually used in the routes definition (prerendered routes are omitted).
-	 * Root layout/error is always included as they are needed for 404 and root errors.
+	 * If `routes` is empty, it means that this manifest is only used for server-side resolution
+	 * and the root layout/error is therefore not needed.
+	 * Else, root layout/error is always included as they are needed for 404 and root errors.
 	 * @type {Set<any>}
 	 */
-	const used_nodes = new Set([0, 1]);
+	const used_nodes = new Set(routes.length > 0 ? [0, 1] : []);
 
 	const server_assets = find_server_assets(build_data, routes);
 
@@ -57,7 +60,11 @@ export function generate_manifest({ build_data, relative_path, routes }) {
 		assets.push(build_data.service_worker);
 	}
 
-	const matchers = new Set();
+	// In case of server side route resolution, we need to include all matchers. Prerendered routes are not part
+	// of the server manifest, and they could reference matchers that then would not be included.
+	const matchers = new Set(
+		build_data.client?.nodes ? Object.keys(build_data.manifest_data.matchers) : undefined
+	);
 
 	/** @param {Array<number | undefined>} indexes */
 	function get_nodes(indexes) {
@@ -90,7 +97,7 @@ export function generate_manifest({ build_data, relative_path, routes }) {
 			assets: new Set(${s(assets)}),
 			mimeTypes: ${s(mime_types)},
 			_: {
-				client: ${s(build_data.client)},
+				client: ${uneval(build_data.client)},
 				nodes: [
 					${(node_paths).map(loader).join(',\n')}
 				],

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

@@ -13,7 +13,7 @@ import { forked } from '../../utils/fork.js';
 import { installPolyfills } from '../../exports/node/polyfills.js';
 import { ENDPOINT_METHODS } from '../../constants.js';
 import { filter_private_env, filter_public_env } from '../../utils/env.js';
-import { resolve_route } from '../../utils/routing.js';
+import { has_server_load, resolve_route } from '../../utils/routing.js';
 import { get_page_config } from '../../utils/route_config.js';
 import { check_feature } from '../../utils/features.js';
 import { createReadableStream } from '@sveltejs/kit/node';
@@ -88,7 +88,7 @@ async function analyse({
 		}
 
 		metadata.nodes[node.index] = {
-			has_server_load: node.server?.load !== undefined || node.server?.trailingSlash !== undefined
+			has_server_load: has_server_load(node)
 		};
 	}
 

packages/kit/src/core/sync/write_client_manifest.js

@@ -10,9 +10,11 @@ import colors from 'kleur';
  * @param {import('types').ValidatedKitConfig} kit
  * @param {import('types').ManifestData} manifest_data
  * @param {string} output
- * @param {Array<{ has_server_load: boolean }>} [metadata]
+ * @param {import('types').ServerMetadata['nodes']} [metadata] If this is omitted, we have to assume that all routes with a `+layout/page.server.js` file have a server load function
  */
 export function write_client_manifest(kit, manifest_data, output, metadata) {
+	const client_routing = kit.router.resolution === 'client';
+
 	/**
 	 * Creates a module that exports a `CSRPageNode`
 	 * @param {import('types').PageNode} node
@@ -47,11 +49,14 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 			write_if_changed(`${output}/nodes/${i}.js`, generate_node(node));
 			return `() => import('./nodes/${i}')`;
 		})
+		// If route resolution happens on the server, we only need the root layout and root error page
+		// upfront, the rest is loaded on demand as the user navigates the app
+		.slice(0, client_routing ? manifest_data.nodes.length : 2)
 		.join(',\n');
 
 	const layouts_with_server_load = new Set();
 
-	const dictionary = dedent`
+	let dictionary = dedent`
 		{
 			${manifest_data.routes
 				.map((route) => {
@@ -108,6 +113,13 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 		}
 	`;
 
+	if (!client_routing) {
+		dictionary = '{}';
+		const root_layout = layouts_with_server_load.has(0);
+		layouts_with_server_load.clear();
+		if (root_layout) layouts_with_server_load.add(0);
+	}
+
 	const client_hooks_file = resolve_entry(kit.files.hooks.client);
 	const universal_hooks_file = resolve_entry(kit.files.hooks.universal);
 
@@ -123,6 +135,8 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 		);
 	}
 
+	// Stringified version of
+	/** @type {import('../../runtime/client/types.js').SvelteKitApp} */
 	write_if_changed(
 		`${output}/app.js`,
 		dedent`
@@ -137,7 +151,7 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 					: ''
 			}
 
-			export { matchers } from './matchers.js';
+			${client_routing ? "export { matchers } from './matchers.js';" : 'export const matchers = {};'}
 
 			export const nodes = [
 				${nodes}
@@ -158,29 +172,31 @@ export function write_client_manifest(kit, manifest_data, output, metadata) {
 
 			export const decoders = Object.fromEntries(Object.entries(hooks.transport).map(([k, v]) => [k, v.decode]));
 
-			export const hash = ${JSON.stringify(kit.router.type === 'hash')};
+			export const hash = ${s(kit.router.type === 'hash')};
 
 			export const decode = (type, value) => decoders[type](value);
 
 			export { default as root } from '../root.${isSvelte5Plus() ? 'js' : 'svelte'}';
 		`
 	);
 
-	// write matchers to a separate module so that we don't
-	// need to worry about name conflicts
-	const imports = [];
-	const matchers = [];
+	if (client_routing) {
+		// write matchers to a separate module so that we don't
+		// need to worry about name conflicts
+		const imports = [];
+		const matchers = [];
 
-	for (const key in manifest_data.matchers) {
-		const src = manifest_data.matchers[key];
+		for (const key in manifest_data.matchers) {
+			const src = manifest_data.matchers[key];
 
-		imports.push(`import { match as ${key} } from ${s(relative_path(output, src))};`);
-		matchers.push(key);
-	}
+			imports.push(`import { match as ${key} } from ${s(relative_path(output, src))};`);
+			matchers.push(key);
+		}
 
-	const module = imports.length
-		? `${imports.join('\n')}\n\nexport const matchers = { ${matchers.join(', ')} };`
-		: 'export const matchers = {};';
+		const module = imports.length
+			? `${imports.join('\n')}\n\nexport const matchers = { ${matchers.join(', ')} };`
+			: 'export const matchers = {};';
 
-	write_if_changed(`${output}/matchers.js`, module);
+		write_if_changed(`${output}/matchers.js`, module);
+	}
 }

packages/kit/src/core/sync/write_server.js

@@ -35,7 +35,6 @@ import { set_manifest, set_read_implementation } from '__sveltekit/server';
 import { set_private_env, set_public_env, set_safe_public_env } from '${runtime_directory}/shared-server.js';
 
 export const options = {
-	app_dir: ${s(config.kit.appDir)},
 	app_template_contains_nonce: ${template.includes('%sveltekit.nonce%')},
 	csp: ${s(config.kit.csp)},
 	csrf_check_origin: ${s(config.kit.csrf.checkOrigin)},
@@ -118,6 +117,8 @@ export function write_server(config, output) {
 		return posixify(path.relative(`${output}/server`, file));
 	}
 
+	// Contains the stringified version of
+	/** @type {import('types').SSROptions} */
 	write_if_changed(
 		`${output}/server/internal.js`,
 		server_template({

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

@@ -659,6 +659,28 @@ export interface KitConfig {
 		 * @since 2.14.0
 		 */
 		type?: 'pathname' | 'hash';
+		/**
+		 * How to determine which route to load when navigating to a new page.
+		 *
+		 * By default, SvelteKit will serve a route manifest to the browser.
+		 * When navigating, this manifest is used (along with the `reroute` hook, if it exists) to determine which components to load and which `load` functions to run.
+		 * Because everything happens on the client, this decision can be made immediately. The drawback is that the manifest needs to be
+		 * loaded and parsed before the first navigation can happen, which may have an impact if your app contains many routes.
+		 *
+		 * Alternatively, SvelteKit can determine the route on the server. This means that for every navigation to a path that has not yet been visited, the server will be asked to determine the route.
+		 * This has several advantages:
+		 * - The client does not need to load the routing manifest upfront, which can lead to faster initial page loads
+		 * - The list of routes is hidden from public view
+		 * - The server has an opportunity to intercept each navigation (for example through a middleware), enabling (for example) A/B testing opaque to SvelteKit
+
+		 * The drawback is that for unvisited paths, resolution will take slightly longer (though this is mitigated by [preloading](https://svelte.dev/docs/kit/link-options#data-sveltekit-preload-data)).
+		 *
+		 * > [!NOTE] When using server-side route resolution and prerendering, the resolution is prerendered along with the route itself.
+		 *
+		 * @default "client"
+		 * @since 2.17.0
+		 */
+		resolution?: 'client' | 'server';
 	};
 	serviceWorker?: {
 		/**