feat: server side route resolution (#13379)

This PR adds server side route resolution to SvelteKit. This means that instead of loading the whole routing manifest in the client, and doing the route resolution there, the server runtime is invoked for each route request.

How this works:
- user clicks on `<a href="/foo/bar">..</a>`
- server call to `_app/route[route].js`, so in this case `_app/routes/foo/bar.js`
- SvelteKit server runtime does route resolution (does this match a route, taking reroutes into account etc) on the server and returns a response that is a JavaScript file containing the route information in a format that can be parsed on the client

What this enables:
- Projects with massive routes can use this to not send so many kilobytes up front to the client, because the client routing manifest would no longer be sent
- You can hide what routes you have
- Because the server is hit for every route resolution, you can put things like edge middleware in front and be confident it is always called, and for example do rewrites (for example for A/B testing) in there

---------

Co-authored-by: Rich Harris <[email protected]>

Author: dummdidumm

.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({