feat: typed route ids (#13864)

Rich-Harris · elliott-with-the-longest-name-on-github · eltigerchino · web-flow · commit a8cc450f7ab4 · 2025-07-24T11:43:18.000-04:00
* add `RouteId` to `$app/types`

* more

* create directory

* hmm

* fix

* changeset

* regenerate

* some basic docs

* oh wow that seemed to work

* test

* ouch

* oh actually lets do this instead

* fix

* couple more, though still doesnt quite fix everything

* forgive me

* fix

* fix

* make url.pathname type safe as well

* oops didnt mean to commit that

* fix

* page.url.pathname needs to account for base path

* resolveRoute -&gt; resolve

* add `asset(...)` function, deprecate `base` and `assets`

* fix

* changesets

* regenerate

* Update packages/kit/src/core/sync/write_types/test/app-types/+page.ts

Co-authored-by: Rich Harris &lt;richard.a.harris@gmail.com&gt;

* Update packages/kit/src/core/sync/write_types/test/app-types/+page.ts

Co-authored-by: Rich Harris &lt;richard.a.harris@gmail.com&gt;

* chore: extract regexes into named functions

* Update documentation/docs/98-reference/20-$app-types.md

* Update documentation/docs/98-reference/20-$app-types.md

Co-authored-by: Rich Harris &lt;richard.a.harris@gmail.com&gt;

* empty

* add an example

* silence error

* fix typo

* link from deprecation notices

* since

---------

Co-authored-by: Elliott Johnson &lt;sejohnson@torchcloudconsulting.com&gt;
Co-authored-by: Tee Ming &lt;chewteeming01@gmail.com&gt;
diff --git a/.changeset/proud-rules-bow.md b/.changeset/proud-rules-bow.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: better type-safety for `page.route.id`, `page.params`, page.url.pathname` and various other places
diff --git a/.changeset/slow-weeks-wave.md b/.changeset/slow-weeks-wave.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: `resolve(...)` and `asset(...)` helpers for resolving paths
diff --git a/.changeset/wicked-bananas-yawn.md b/.changeset/wicked-bananas-yawn.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: Add `$app/types` module with `Asset`, `RouteId`, `Pathname`, `ResolvedPathname` `RouteParams<T>` and `LayoutParams<T>`
diff --git a/documentation/docs/98-reference/20-$app-types.md b/documentation/docs/98-reference/20-$app-types.md
@@ -0,0 +1,91 @@
+---
+title: $app/types
+---
+
+This module contains generated types for the routes in your app.
+
+<blockquote class="since note">
+	<p>Available since 2.26</p>
+</blockquote>
+
+```js
+// @noErrors
+import type { RouteId, RouteParams, LayoutParams } from '$app/types';
+```
+
+## Asset
+
+A union of all the filenames of assets contained in your `static` directory.
+
+<div class="ts-block">
+
+```dts
+type Asset = '/favicon.png' | '/robots.txt';
+```
+
+</div>
+
+## RouteId
+
+A union of all the route IDs in your app. Used for `page.route.id` and `event.route.id`.
+
+<div class="ts-block">
+
+```dts
+type RouteId = '/' | '/my-route' | '/my-other-route/[param]';
+```
+
+</div>
+
+## Pathname
+
+A union of all valid pathnames in your app.
+
+<div class="ts-block">
+
+```dts
+type Pathname = '/' | '/my-route' | `/my-other-route/${string}` & {};
+```
+
+</div>
+
+## ResolvedPathname
+
+`Pathname`, but possibly prefixed with a [base path](https://svelte.dev/docs/kit/configuration#paths). Used for `page.url.pathname`.
+
+<div class="ts-block">
+
+```dts
+type Pathname = `${'' | `/${string}`}/` | `${'' | `/${string}`}/my-route` | `${'' | `/${string}`}/my-other-route/${string}` | {};
+```
+
+</div>
+
+## RouteParams
+
+A utility for getting the parameters associated with a given route.
+
+```ts
+// @errors: 2552
+type BlogParams = RouteParams<'/blog/[slug]'>; // { slug: string }
+```
+
+<div class="ts-block">
+
+```dts
+type RouteParams<T extends RouteId> = { /* generated */ } | Record<string, never>;
+```
+
+</div>
+
+## LayoutParams
+
+A utility for getting the parameters associated with a given layout, which is similar to `RouteParams` but also includes optional parameters for any child route.
+
+<div class="ts-block">
+
+```dts
+type RouteParams<T extends RouteId> = { /* generated */ } | Record<string, never>;
+```
+
+</div>
diff --git a/packages/adapter-auto/tsconfig.json b/packages/adapter-auto/tsconfig.json
@@ -7,7 +7,8 @@
 		"target": "es2022",
 		"module": "node16",
 		"moduleResolution": "node16",
-		"baseUrl": "."
+		"baseUrl": ".",
+		"skipLibCheck": true
 	},
 	"include": ["**/*.js"]
 }
diff --git a/packages/adapter-node/tsconfig.json b/packages/adapter-node/tsconfig.json
@@ -11,7 +11,8 @@
 		"baseUrl": ".",
 		"paths": {
 			"@sveltejs/kit": ["../kit/types/index"]
-		}
+		},
+		"skipLibCheck": true
 	},
 	"include": ["index.js", "src/**/*.js", "tests/**/*.js", "internal.d.ts", "utils.js"],
 	"exclude": ["tests/smoke.spec_disabled.js"]
diff --git a/packages/adapter-static/tsconfig.json b/packages/adapter-static/tsconfig.json
@@ -11,7 +11,8 @@
 		"baseUrl": ".",
 		"paths": {
 			"@sveltejs/kit": ["../kit/types/index"]
-		}
+		},
+		"skipLibCheck": true
 	},
 	"include": ["index.js", "test/utils.js"]
 }
diff --git a/packages/adapter-vercel/tsconfig.json b/packages/adapter-vercel/tsconfig.json
@@ -12,7 +12,8 @@
 		"baseUrl": ".",
 		"paths": {
 			"@sveltejs/kit": ["../kit/types/index"]
-		}
+		},
+		"skipLibCheck": true
 	},
 	"include": ["*.js", "files/**/*.js", "internal.d.ts", "test/**/*.js"]
 }
diff --git a/packages/kit/scripts/generate-dts.js b/packages/kit/scripts/generate-dts.js
@@ -1,5 +1,5 @@
 import { createBundle } from 'dts-buddy';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 
 await createBundle({
 	output: 'types/index.d.ts',
@@ -28,3 +28,9 @@ if (types.includes('__sveltekit/')) {
 			types
 	);
 }
+
+// this is hacky as all hell but it gets the tests passing. might be a bug in dts-buddy?
+// prettier-ignore
+writeFileSync('./types/index.d.ts', types.replace("declare module '$app/server' {", `declare module '$app/server' {
+	// @ts-ignore
+	import { LayoutParams as AppLayoutParams, RouteId as AppRouteId } from '$app/types'`));
diff --git a/packages/kit/src/core/sync/write_tsconfig.js b/packages/kit/src/core/sync/write_tsconfig.js
@@ -98,7 +98,10 @@ export function get_tsconfig(kit) {
 	const config = {
 		compilerOptions: {
 			// generated options
-			paths: get_tsconfig_paths(kit),
+			paths: {
+				...get_tsconfig_paths(kit),
+				'$app/types': ['./types/index.d.ts']
+			},
 			rootDirs: [config_relative('.'), './types'],
 
 			// essential options
diff --git a/packages/kit/src/core/sync/write_tsconfig.spec.js b/packages/kit/src/core/sync/write_tsconfig.spec.js
@@ -20,6 +20,7 @@ test('Creates tsconfig path aliases from kit.alias', () => {
 	// $lib isn't part of the outcome because there's a "path exists"
 	// check in the implementation
 	expect(compilerOptions.paths).toEqual({
+		'$app/types': ['./types/index.d.ts'],
 		simpleKey: ['../simple/value'],
 		'simpleKey/*': ['../simple/value/*'],
 		key: ['../value'],
diff --git a/packages/kit/src/core/sync/write_types/index.js b/packages/kit/src/core/sync/write_types/index.js
@@ -5,6 +5,15 @@ import MagicString from 'magic-string';
 import { posixify, rimraf, walk } from '../../../utils/filesystem.js';
 import { compact } from '../../../utils/array.js';
 import { ts } from '../ts.js';
+import { s } from '../../../utils/misc.js';
+
+const remove_relative_parent_traversals = (/** @type {string} */ path) =>
+	path.replace(/\.\.\//g, '');
+const replace_optional_params = (/** @type {string} */ id) =>
+	id.replace(/\/\[\[[^\]]+\]\]/g, '${string}');
+const replace_required_params = (/** @type {string} */ id) =>
+	id.replace(/\/\[[^\]]+\]/g, '/${string}');
+const is_whitespace = (/** @type {string} */ char) => /\s/.test(char);
 
 /**
  *  @typedef {{
@@ -35,7 +44,9 @@ export function write_all_types(config, manifest_data) {
 	const types_dir = `${config.kit.outDir}/types`;
 
 	// empty out files that no longer need to exist
-	const routes_dir = posixify(path.relative('.', config.kit.files.routes)).replace(/\.\.\//g, '');
+	const routes_dir = remove_relative_parent_traversals(
+		posixify(path.relative('.', config.kit.files.routes))
+	);
 	const expected_directories = new Set(
 		manifest_data.routes.map((route) => path.join(routes_dir, route.id))
 	);
@@ -49,6 +60,65 @@ export function write_all_types(config, manifest_data) {
 		}
 	}
 
+	/** @type {string[]} */
+	const pathnames = [];
+
+	/** @type {string[]} */
+	const dynamic_routes = [];
+
+	/** @type {string[]} */
+	const layouts = [];
+
+	for (const route of manifest_data.routes) {
+		if (route.params.length > 0) {
+			const params = route.params.map((p) => `${p.name}${p.optional ? '?:' : ':'} string`);
+			const route_type = `${s(route.id)}: { ${params.join('; ')} }`;
+
+			dynamic_routes.push(route_type);
+
+			pathnames.push(`\`${replace_required_params(replace_optional_params(route.id))}\` & {}`);
+		} else {
+			pathnames.push(s(route.id));
+		}
+
+		/** @type {Map<string, boolean>} */
+		const child_params = new Map(route.params.map((p) => [p.name, p.optional]));
+
+		for (const child of manifest_data.routes.filter((r) => r.id.startsWith(route.id))) {
+			for (const p of child.params) {
+				if (!child_params.has(p.name)) {
+					child_params.set(p.name, true); // always optional
+				}
+			}
+		}
+
+		const layout_params = Array.from(child_params)
+			.map(([name, optional]) => `${name}${optional ? '?:' : ':'} string`)
+			.join('; ');
+
+		const layout_type = `${s(route.id)}: ${layout_params.length > 0 ? `{ ${layout_params} }` : 'undefined'}`;
+		layouts.push(layout_type);
+	}
+
+	try {
+		fs.mkdirSync(types_dir, { recursive: true });
+	} catch {}
+
+	fs.writeFileSync(
+		`${types_dir}/index.d.ts`,
+		[
+			`type DynamicRoutes = {\n\t${dynamic_routes.join(';\n\t')}\n};`,
+			`type Layouts = {\n\t${layouts.join(';\n\t')}\n};`,
+			// we enumerate these rather than doing `keyof Routes` so that the list is visible on hover
+			`export type RouteId = ${manifest_data.routes.map((r) => s(r.id)).join(' | ')};`,
+			'export type RouteParams<T extends RouteId> = T extends keyof DynamicRoutes ? DynamicRoutes[T] : Record<string, never>;',
+			'export type LayoutParams<T extends RouteId> = Layouts[T] | Record<string, never>;',
+			`export type Pathname = ${pathnames.join(' | ')};`,
+			'export type ResolvedPathname = `${"" | `/${string}`}${Pathname}`;',
+			`export type Asset = ${manifest_data.assets.map((asset) => s('/' + asset.file)).join(' | ') || 'never'};`
+		].join('\n\n')
+	);
+
 	// Read/write meta data on each invocation, not once per node process,
 	// it could be invoked by another process in the meantime.
 	const meta_data_file = `${types_dir}/route_meta_data.json`;
@@ -174,7 +244,9 @@ function create_routes_map(manifest_data) {
  * @param {Set<string>} [to_delete]
  */
 function update_types(config, routes, route, to_delete = new Set()) {
-	const routes_dir = posixify(path.relative('.', config.kit.files.routes)).replace(/\.\.\//g, '');
+	const routes_dir = remove_relative_parent_traversals(
+		posixify(path.relative('.', config.kit.files.routes))
+	);
 	const outdir = path.join(config.kit.outDir, 'types', routes_dir, route.id);
 
 	// now generate new types
@@ -733,7 +805,7 @@ export function tweak_types(content, is_server) {
 						if (declaration.type) {
 							let a = declaration.type.pos;
 							const b = declaration.type.end;
-							while (/\s/.test(content[a])) a += 1;
+							while (is_whitespace(content[a])) a += 1;
 
 							const type = content.slice(a, b);
 							code.remove(declaration.name.end, declaration.type.end);
@@ -805,7 +877,7 @@ export function tweak_types(content, is_server) {
 						if (declaration.type) {
 							let a = declaration.type.pos;
 							const b = declaration.type.end;
-							while (/\s/.test(content[a])) a += 1;
+							while (is_whitespace(content[a])) a += 1;
 
 							const type = content.slice(a, b);
 							code.remove(declaration.name.end, declaration.type.end);
diff --git a/packages/kit/src/core/sync/write_types/index.spec.js b/packages/kit/src/core/sync/write_types/index.spec.js
@@ -1,4 +1,5 @@
 import { execSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assert, expect, test } from 'vitest';
@@ -33,15 +34,14 @@ test('Creates correct $types', { timeout: 6000 }, () => {
 	// To save us from creating a real SvelteKit project for each of the tests,
 	// we first run the type generation directly for each test case, and then
 	// call `tsc` to check that the generated types are valid.
-	run_test('actions');
-	run_test('simple-page-shared-only');
-	run_test('simple-page-server-only');
-	run_test('simple-page-server-and-shared');
-	run_test('layout');
-	run_test('layout-advanced');
-	run_test('slugs');
-	run_test('slugs-layout-not-all-pages-have-load');
-	run_test('param-type-inference');
+	const directories = fs
+		.readdirSync(cwd)
+		.filter((dir) => fs.statSync(`${cwd}/${dir}`).isDirectory());
+
+	for (const dir of directories) {
+		run_test(dir);
+	}
+
 	try {
 		execSync('pnpm testtypes', { cwd });
 	} catch (e) {
diff --git a/packages/kit/src/core/sync/write_types/test/app-types/+page.ts b/packages/kit/src/core/sync/write_types/test/app-types/+page.ts
@@ -0,0 +1,30 @@
+import type { RouteId, RouteParams, Pathname } from './.svelte-kit/types/index.d.ts';
+
+declare let id: RouteId;
+
+// okay
+id = '/';
+id = '/foo/[bar]/[baz]';
+
+// @ts-expect-error
+id = '/nope';
+
+// read `id` otherwise it is treated as unused
+id;
+
+declare let params: RouteParams<'/foo/[bar]/[baz]'>;
+
+// @ts-expect-error
+params.foo; // not okay
+params.bar; // okay
+params.baz; // okay
+
+declare let pathname: Pathname;
+
+// @ts-expect-error
+pathname = '/nope';
+pathname = '/foo';
+pathname = '/foo/1/2';
+
+// read `pathname` otherwise it is treated as unused
+pathname;
diff --git a/packages/kit/src/core/sync/write_types/test/app-types/foo/[bar]/[baz]/+page.ts b/packages/kit/src/core/sync/write_types/test/app-types/foo/[bar]/[baz]/+page.ts
diff --git a/packages/kit/src/core/sync/write_types/test/tsconfig.json b/packages/kit/src/core/sync/write_types/test/tsconfig.json
@@ -14,6 +14,6 @@
 			"types": ["../../../../types/internal"]
 		}
 	},
-	"include": ["./**/*.js"],
+	"include": ["./**/*.js", "./**/*.ts"],
 	"exclude": ["./**/.svelte-kit/**"]
 }
diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts
diff --git a/packages/kit/src/runtime/app/paths/index.js b/packages/kit/src/runtime/app/paths/index.js
diff --git a/packages/kit/src/runtime/app/paths/types.d.ts b/packages/kit/src/runtime/app/paths/types.d.ts
diff --git a/packages/kit/test/apps/basics/src/routes/+layout.svelte b/packages/kit/test/apps/basics/src/routes/+layout.svelte
diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@sveltejs/kit': minor
 +---
++
 +feat: better type-safety for `page.route.id`, `page.params`, page.url.pathname` and various other places