feat: typed route ids #13864

Rich-Harris · 2025-06-07T20:01:16Z

resolves #11386

This is long overdue, but @jycouet goaded me into working on it with the 1.0 release of vite-plugin-kit-routes 🎉

Everyone should have type safety when dealing with routes!

This PR adds a new generated $app/types module which exports three types:

RouteId is a union of all the routes in your app ('/' | '/about' | '/blog' | '/blog/[slug]' etc)
RouteParams<T extends RouteId> is a utility that gives you the type of the params for a given route
LayoutParams<T extends RouteId> is the same, but also gives you the type of any children of T (for example, if you're in the /blog layout, the route could be either /blog or /blog/[slug], so slug is an optional param

Most of the time you won't use these types directly, but via things like page.route.id and resolveRoute:

I couldn't figure out a sensible way to add a test for this. Maybe someone else can, if not then I'm not too worried about it.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
This message body should clearly illustrate what problems it solves.
Ideally, include a test that fails without this PR but passes with it.

Tests

Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

Edits

Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.

changeset-bot · 2025-06-07T20:01:21Z

🦋 Changeset detected

Latest commit: de26113

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/kit	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

svelte-docs-bot · 2025-06-07T20:01:47Z

Preview: https://svelte-dev-git-preview-kit-13864-svelte.vercel.app/

jycouet · 2025-06-07T20:20:08Z

Haha noice!
Let's link to: #11386

Would you consider two more things ?

1/ being able to specify searchParams in like +page.ts

export const params = {
  limit: 11,
  search: ''
}

2/ How to add things in the list of resolveRoute ? To manage external links ?

Rich-Harris · 2025-06-07T20:25:32Z

Typing search params would be great but I think that's a separate issue and it shouldn't hold up this PR. As for resolveRoute, I'm not sure what you mean — it's only meant to be used with the routes of your app, why would you need to do stuff with external links?

Rich-Harris · 2025-06-07T20:29:36Z

had to bump the test timeout quite a bit, might be worth running unit tests in a separate workflow

jycouet · 2025-06-07T20:37:52Z

Typing search params would be great but I think that's a separate issue and it shouldn't hold up this PR. As for resolveRoute, I'm not sure what you mean — it's only meant to be used with the routes of your app, why would you need to do stuff with external links?

Perfect to have a follow-up PR for searchParams, yeah, let's do this step by step ;)

I like to have a common way to manage ALL links (internal & external).

<!-- 🤞 before, hardcoded string, error prone -->
<a href="https://bsky.app/profile/jyc.dev">Bluesky</a>

<!-- ✅ after, typechecked route, no more errors -->
<a href={route('bluesky', { handle: 'jyc.dev' })}>Bluesky</a>

Today, I just need to feed the config like this: (similar path structure to "create" params)

plugins: [
    // ...
    kitRoutes({
      LINKS: {
        bluesky: 'https://bsky.app/profile/[handle]',
      }
    }),
],

Of course, it can be a separate issue to think a bit how to feed this info. But in general, what's your feeling ?

vite-plugin-kit-routes DEPRECATED s00n 🎉

jycouet · 2025-06-07T20:39:45Z

had to bump the test timeout quite a bit, might be worth running unit tests in a separate workflow

Not tonight, but let me know where/how I can contribute to this feature.

eltigerchino · 2025-06-09T05:03:07Z

packages/adapter-auto/tsconfig.json

@@ -7,7 +7,8 @@
 		"target": "es2022",
 		"module": "node16",
 		"moduleResolution": "node16",
-		"baseUrl": "."
+		"baseUrl": ".",
+		"skipLibCheck": true


~~Do we need skipLibCheck? I've tried running pnpm check without it and didn't bump into any issues for the adapters.~~

EDIT: Alright, I'm seeing the errors now.

I'm thinking of looking into dts-buddy to see if we can get it to keep the // @ts-ignore comments in the generated types so that we don't need skipLibCheck here. It seems like the best way to tell TypeScript "this type doesn't exist yet but will be generated" until something like microsoft/TypeScript#31894 comes along. Do you think this is worth looking into?

Worth a shot I guess, though dts-buddy is operating on emitted declaration files and I'm pretty sure the comments are lost by that point - might be tricky to correctly recover them from the source

I managed to get it working in sveltejs/dts-buddy#110 . This should remove the need for the hack in generate-dts.js to preserve the @ts-ignore comment.

The ts-ignore is only preserved if it meets these two rules:

It has to be a multi-line comment /** @ts-ignore ... */ so that it gets recognised as jsdoc

It has to be above the start of a statement instead of in the middle of it such as in line 26 here https://github.com/sveltejs/kit/pull/13864/files#diff-a174e22e6d675073a963705b97687d42e219c2e05eb1cd6d5811c2581d416a8e

ah nice. I don't have time to review that PR right now but I left a comment over there to remind myself to come back and clean this up later

Rich-Harris · 2025-06-09T15:29:19Z

For external links: I could imagine a future addition like this, which should be all that's needed from a configuration perspective:

// svelte.config.js
export default {
  kit: {
    paths: {
      external: {
        bluesky: 'https://bsky.app/profile/[handle]'
      }
    }
  }
};

Rich-Harris · 2025-06-09T15:29:50Z

Just realised that resolveRoute('/foo') errors because of a missing second argument, which is the opposite of what's supposed to happen. Investigating

Co-authored-by: Rich Harris <richard.a.harris@gmail.com>

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

benmccann · 2025-06-15T18:38:11Z

#13881 is a PR against this branch that adds additional tests

packages/kit/src/core/sync/write_types/index.js

Co-authored-by: Rich Harris <richard.a.harris@gmail.com>

elliott-with-the-longest-name-on-github

Does this only get docs on types? I couldn't figure out anywhere else we reference it.

charbelnicolas · 2025-07-25T00:08:01Z

The following code no longer works when using resolve() for href and export const trailingSlash = 'always';

<Link href={resolve('/dashboard/settings/')} label="SETTINGS" />

link.svelte

<script>

	import { page } from '$app/stores';

	let { href, label } = $props();

</script>

<a href={href} class="header-button font-medium" class:selected-link={$page.url.pathname === href} aria-label={label}>

	{label}

</a>

$page.url.pathname === href is never the same, one has a trailing slash, the other doesn't.

href = /portal/dashboard/settings and $page.url.pathname = /portal/dashboard/settings/

If using trailingSlash = always, resolve() should add it too IMO.

Please let me know if I'm wrong and should do a work around this issue.

charbelnicolas · 2025-07-25T01:48:41Z

The following code no longer works when using resolve() for href and export const trailingSlash = 'always';

<Link href={resolve('/dashboard/settings/')} label="SETTINGS" />

link.svelte
<script>

	import { page } from '$app/stores';

	let { href, label } = $props();

</script>

<a href={href} class="header-button font-medium" class:selected-link={$page.url.pathname === href} aria-label={label}>

	{label}

</a>
$page.url.pathname === href is never the same, one has a trailing slash, the other doesn't.

href = /portal/dashboard/settings and $page.url.pathname = /portal/dashboard/settings/

If using trailingSlash = always, resolve() should add it too IMO.

Please let me know if I'm wrong and should do a work around this issue.

I'm using let hrefWithSlash = $derived(${href}/); as a simple workaround but we shouldn't need any workarounds :)

Rich-Harris · 2025-07-25T01:53:35Z

Please open an issue rather than commenting on a closed PR, where it will get lost

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

Rich-Harris added 6 commits June 7, 2025 12:53

add RouteId to $app/types

74c0fd7

more

c95a69f

create directory

4fe5f0b

hmm

5669c42

fix

3e6b274

changeset

df2293d

Rich-Harris added 3 commits June 7, 2025 16:03

regenerate

039fa0f

some basic docs

e2afa93

oh wow that seemed to work

42ea4f8

Rich-Harris added 2 commits June 7, 2025 16:25

test

26beba7

ouch

5865e34

Rich-Harris added 8 commits June 7, 2025 20:01

oh actually lets do this instead

e155d92

fix

a483961

couple more, though still doesnt quite fix everything

7987509

forgive me

7cf2cfc

fix

8c8c037

fix

c6c3355

make url.pathname type safe as well

cfd16ed

oops didnt mean to commit that

c000bb4

eltigerchino added the feature / enhancement New feature or request label Jun 9, 2025

eltigerchino reviewed Jun 9, 2025

View reviewed changes

elliott-with-the-longest-name-on-github and others added 2 commits June 12, 2025 10:22

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

96de94b

Co-authored-by: Rich Harris <richard.a.harris@gmail.com>

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

5a30a83

Co-authored-by: Rich Harris <richard.a.harris@gmail.com>

Rich-Harris commented Jun 12, 2025

View reviewed changes

documentation/docs/98-reference/20-$app-types.md Outdated Show resolved Hide resolved

chore: extract regexes into named functions

eac2a0e

github-advanced-security bot found potential problems Jun 16, 2025

View reviewed changes

packages/kit/src/core/sync/write_types/index.js Dismissed Show dismissed Hide dismissed

Rich-Harris and others added 2 commits June 17, 2025 13:09

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

5445a93

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

22b26dc

Co-authored-by: Rich Harris <richard.a.harris@gmail.com>

Rich-Harris mentioned this pull request Jun 18, 2025

Pass params to +layout.svelte and +page.svelte components #13904

Closed

Rich-Harris added 5 commits July 23, 2025 18:41

merge main

bb882fa

empty

8895442

add an example

66c209d

silence error

f80faf1

fix typo

a73f34a

elliott-with-the-longest-name-on-github approved these changes Jul 24, 2025

View reviewed changes

Rich-Harris added 2 commits July 24, 2025 11:02

link from deprecation notices

7f5b752

since

de26113

Rich-Harris merged commit a8cc450 into main Jul 24, 2025
21 checks passed

Rich-Harris deleted the typed-route-ids branch July 24, 2025 15:43

github-actions bot mentioned this pull request Jul 24, 2025

Version Packages #14040

Merged

peppasd mentioned this pull request Jul 24, 2025

page.url.pathname types are wrong inside layout groups #14043

Closed

AndersRobstad mentioned this pull request Jul 25, 2025

navigating.from.route.id is typed as string and not RouteId #14048

Closed

Rich-Harris mentioned this pull request Jul 25, 2025

feat: preserve @ts-ignore for generated types sveltejs/dts-buddy#110

Open

eltigerchino mentioned this pull request Jul 29, 2025

docs: "What's new in Svelte" August newsletter sveltejs/svelte.dev#1433

Merged

luanbt21 reviewed Aug 1, 2025

View reviewed changes

documentation/docs/98-reference/20-$app-types.md Show resolved Hide resolved

This was referenced Aug 6, 2025

docs: correct ResolvedPathname type name in the example code block #14122

Merged

${base}/foo -> resolve('/foo') #13840

Closed

Uh oh!

feat: typed route ids #13864

feat: typed route ids #13864

Conversation

Rich-Harris commented Jun 7, 2025 • edited by eltigerchino Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Changesets

Edits

Uh oh!

changeset-bot bot commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

svelte-docs-bot bot commented Jun 7, 2025

Uh oh!

jycouet commented Jun 7, 2025

Uh oh!

Rich-Harris commented Jun 7, 2025

Uh oh!

Rich-Harris commented Jun 7, 2025

Uh oh!

jycouet commented Jun 7, 2025

Uh oh!

jycouet commented Jun 7, 2025

Uh oh!

eltigerchino Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eltigerchino Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rich-Harris Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

eltigerchino Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rich-Harris Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Rich-Harris commented Jun 9, 2025

Uh oh!

Rich-Harris commented Jun 9, 2025

Uh oh!

Uh oh!

benmccann commented Jun 15, 2025

Uh oh!

Uh oh!

elliott-with-the-longest-name-on-github left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

charbelnicolas commented Jul 25, 2025

Uh oh!

charbelnicolas commented Jul 25, 2025

Uh oh!

Rich-Harris commented Jul 25, 2025

Uh oh!

Uh oh!

Uh oh!

Rich-Harris commented Jun 7, 2025 •

edited by eltigerchino

Loading

changeset-bot bot commented Jun 7, 2025 •

edited

Loading

eltigerchino Jun 9, 2025 •

edited

Loading

eltigerchino Jun 9, 2025 •

edited

Loading

eltigerchino Jun 20, 2025 •

edited

Loading