breaking: remove param files in folder in favor of `params.js/ts` file by dummdidumm · Pull Request #16189 · sveltejs/kit

dummdidumm · 2026-06-26T22:25:23Z

Instead of having to declare one param matcher per file, you now declare all of them within one file. A defineParams function both helps with declaring them in a type-safe way and also normalizes the property values: You can either parse a standard schema object, or a function that either throws or returns the parsed value (if you don't want to bring in a schema library).

closes #10407

Kudos to @phi-bre for suggesting this in #16148 (comment)

basically implements #10407 (comment): - new `parse` function can be exported from `params/someMatcher.js` - can be either alongside `match` or standalone - if it throws it counts as invalid and the route will not be matched closes #10407

match can now also be a standard schema. If it parses you get the transformed value. If it throws it counts as invalid and the route will not be matched. closes #10407

…`'~standard'` property, so callable Standard Schemas (e.g. ArkType) are misclassified as plain predicate functions, breaking validation and transformation. This commit fixes the issue reported at packages/kit/src/utils/routing.js:139 ## Bug `ParamMatcher` is typed as `((param: string) => boolean) | StandardSchemaV1<string, any>`. Several headline Standard Schema implementations expose their schema as a **callable function that also carries a `'~standard'` property**. ArkType is the canonical example: ```js const t = type('string.numeric.parse'); t('42'); // → 42 (parsed value, or an ArkErrors object on failure) t['~standard'].validate('42'); // also available ``` In the original `run_matcher`, the `typeof matcher === 'function'` branch comes first: ```js if (typeof matcher === 'function') { return matcher(value) ? { success: true, value } : { success: false }; } if ('~standard' in matcher) { ... } ``` Because an ArkType schema is a function, it never reaches the `'~standard'` branch. Instead `matcher(value)` is called and its return value treated as a boolean: - **Invalid input**: ArkType returns a truthy `ArkErrors` object → treated as a *successful* match, and the raw, untransformed string is stored as the param value. The route matches when it should not. - **Valid input that transforms to a falsy value** (e.g. `0`, empty string): the truthiness check fails → the route is incorrectly rejected. So both validation and transformation are broken for callable Standard Schemas. ## Fix Reorder the checks so `'~standard'` is tested first. `'~standard' in matcher` works on functions too (functions are objects), so a callable Standard Schema is now routed through the proper `validate` path. Plain predicate functions lack the `'~standard'` property and correctly fall through to the function branch. ```js function run_matcher(matcher, value) { if ('~standard' in matcher) { const result = matcher['~standard'].validate(value); if (result instanceof Promise || result.issues) { return { success: false }; } return { success: true, value: result.value }; } if (typeof matcher === 'function') { return matcher(value) ? { success: true, value } : { success: false }; } return { success: false }; } ``` Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: dummdidumm <sholthausen@web.de>

@phi-bre

Instead of having to declare one param matcher per file, you now declare all of them within one file. A `defineParams` function both helps with declaring them in a type-safe way and also normalizes the property values: You can either parse a standard schema object, or a function that either throws or returns the parsed value (if you don't want to bring in a schema library). closes #10407 Kudos to @phi-bre for suggesting this in #16148 (comment)

changeset-bot · 2026-06-26T22:25:28Z

🦋 Changeset detected

Latest commit: 6067b3a

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	Major

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 · 2026-06-26T22:27:00Z

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

…cing the invalid path `src/params/.js` instead of `src/params.js`. This commit fixes the issue reported at packages/kit/src/core/sync/write_types/index.js:605 ## Bug In `generate_params_type` (`write_types/index.js:606`) and the identical logic in `write_non_ambient.js:101`, the fallback used when `resolve_entry` returns `null` was: ```js path.join(config.kit.files.params.replace(/.(js|ts)$/, ''), '.js'); ``` `config.kit.files.params` defaults to `path.join(files.src, 'params')` → `src/params` (no extension). The `.replace(/.(js|ts)$/, '')` is a no-op there, and `path.join('src/params', '.js')` inserts a path separator, yielding `src/params/.js`. Even when the config value has an extension (e.g. `src/params.ts`), the replace strips it to `src/params` and `path.join` again yields `src/params/.js`. Verified with Node: ``` $ node -e "console.log(require('path').join('src/params', '.js'))" src/params/.js ``` ### Trigger / impact When a route references a matcher but `resolve_entry(config.kit.files.params)` returns `null` (params file not found at resolution time), the generated `$types`/app-types contain an import from the broken path `src/params/.js` instead of `src/params.js`, producing invalid type imports. ## Fix Replaced `path.join(base, '.js')` with string concatenation `base + '.js'` in both locations: ```js config.kit.files.params.replace(/.(js|ts)$/, '') + '.js'; ``` Verified output is now `src/params.js` for both `src/params` and `src/params.ts` inputs. Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: dummdidumm <sholthausen@web.de>

adiguba · 2026-06-28T07:46:22Z

Hello,

Two remarks.

Did the resolve() will be correctly typed ?

For example if I have this params :

export const params = defineParams({
  details: v.picklist(['min', 'standard', 'max']);
});

I think this should be typed accordingly :

resolve('/info/[details=details]', { details: 'min' }); // OK
resolve('/info/[details=details]', { details: 'minimum' }); // Type Error

It would be nice to have an optional format() method to complement parse().
This method would be used by resolve() to build the URL

For example, if I have bigint as uid, and I want to use it as hexadecimal on the URL :

export const params = defineParams({
  uid: {
    // parse the uid as a hexa BigInt :
    parse: v.pipe(v.string(),v.transform((value) => BigInt(`0x${value}`)),
    // format the BigInt in hexa
    format: (value) => value.toString(16)
   }
});

Co-authored-by: Conduitry <git@chor.date>

sacrosanctic · 2026-06-30T17:29:23Z

Food for thought, param.ts in singular form.

Though prior art is mixed:

/params/[matcher].ts
env.ts
routes
hooks.ts

sirkostya009 · 2026-06-30T22:09:07Z

this is better than what we currently got. one question though, will this feature be backported to kit v2 behind an experimental flag? docs dont mention anything about that

dummdidumm · 2026-07-01T14:41:45Z

no there are no plans to backport this at the moment

…t for match

pkg-svelte-dev · 2026-07-01T19:47:06Z

Install the latest version of @sveltejs/kit from 6067b3a:

pnpm add https://pkg.svelte.dev/@sveltejs/kit/c/6067b3a96161b9ceec13693f9c91aeaed6f3ff6f

Open in pkg.svelte.dev: https://pkg.svelte.dev/repos/kit/pr/16189

Rich-Harris · 2026-07-02T00:13:03Z

param.ts in singular form.

that wouldn't really make sense. hooks, routes, params are all plural. env isn't, because it's describing the environment as a whole, rather than multiple environments

…try-catch on server.

vercel

Additional Suggestion:

A throwing param matcher breaks client-side navigation (silent no-op / unhandled promise rejection) even though the server handles the same throw gracefully, creating a server/client asymmetry introduced by commit f5479de.

dummdidumm · 2026-07-02T21:34:06Z

Vercel is right, but I don't see a good way how we can sensibly handle this. We could fall back to a full page reload to get the better error message eventually that way.

// in function navigate(...)
	try {
		intent ??= await get_navigation_intent(url, false);
	} catch {
		// Likely a matcher threw unexpectedly. Fall back to the server to get a proper error page.
		return await native_navigation(url, replace_state);
	}

Anything more would mean polluting the whole navigation code for such an edge case and that is not worth it. It should never happen anyway.

…' into matcher-params-file

dummdidumm and others added 7 commits June 23, 2026 22:05

feat: add parse function to matcher files

c67990f

basically implements #10407 (comment): - new `parse` function can be exported from `params/someMatcher.js` - can be either alongside `match` or standalone - if it throws it counts as invalid and the route will not be matched closes #10407

oops

fcd721d

feat: allow param matcher to be a standard schema

834db22

match can now also be a standard schema. If it parses you get the transformed value. If it throws it counts as invalid and the route will not be matched. closes #10407

Merge branch 'version-3' into matcher-schema

e169952

oops

292955c

vercel Bot reviewed Jun 26, 2026

View reviewed changes

Comment thread packages/kit/src/utils/params.js

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

vercel Bot and others added 3 commits June 26, 2026 22:50

move around

8e076d9

lint

088e906

dummdidumm marked this pull request as draft June 26, 2026 22:55

dummdidumm added 2 commits June 27, 2026 21:46

lint

de6abd8

ugh

7b77828

dummdidumm added 2 commits June 29, 2026 11:13

fix

65b5b64

fix

7c73660

Conduitry changed the title ~~breaking: remove param files in folder in favor or params.js/ts file~~ breaking: remove param files in folder in favor of params.js/ts file Jun 29, 2026

Conduitry reviewed Jun 29, 2026

View reviewed changes

Comment thread .changeset/ten-lands-send.md Outdated

Update .changeset/ten-lands-send.md

4f2e270

Co-authored-by: Conduitry <git@chor.date>

dummdidumm marked this pull request as ready for review June 29, 2026 20:22

dummdidumm marked this pull request as draft June 29, 2026 20:22

dummdidumm marked this pull request as ready for review June 30, 2026 10:31

teemingc added the breaking change label Jun 30, 2026

restrict output types to be able to infer input for resolve and outpu…

bf31055

…t for match

dummdidumm added 3 commits July 1, 2026 18:15

Merge branch 'version-3' into matcher-params-file

bf932ca

ugh

9fb6f4a

get lost eslint

b9486b1

instead of throwing, make undefined the value for "no match". Also …

f5479de

…try-catch on server.

vercel Bot reviewed Jul 2, 2026

View reviewed changes

dummdidumm and others added 2 commits July 2, 2026 23:34

ASIODJQOWIDQLWKCALSKCJGNNNRRNRRRR

0303720

Merge branch 'version-3' into matcher-params-file

9937f8a

Rich-Harris reviewed Jul 2, 2026

View reviewed changes

Comment thread documentation/docs/30-advanced/10-advanced-routing.md Outdated

Rich-Harris reviewed Jul 2, 2026

View reviewed changes

Comment thread packages/kit/src/exports/params.js Outdated

Rich-Harris reviewed Jul 2, 2026

View reviewed changes

Comment thread packages/kit/src/runtime/server/respond.js Outdated

Rich-Harris reviewed Jul 2, 2026

View reviewed changes

Comment thread packages/kit/src/utils/routing.js Outdated

dummdidumm added 3 commits July 3, 2026 22:03

feedback + be more honest about defineParam's return type

f57df6e

Merge remote-tracking branch 'refs/remotes/origin/matcher-params-file…

e5b1422

…' into matcher-params-file

gah

6067b3a

Uh oh!

Uh oh!

Conversation

dummdidumm commented Jun 26, 2026

Uh oh!

changeset-bot Bot commented Jun 26, 2026 • 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 26, 2026

Uh oh!

Uh oh!

Uh oh!

adiguba commented Jun 28, 2026

Uh oh!

Uh oh!

sacrosanctic commented Jun 30, 2026

Uh oh!

sirkostya009 commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dummdidumm commented Jul 1, 2026

Uh oh!

pkg-svelte-dev Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Rich-Harris commented Jul 2, 2026

Uh oh!

vercel Bot left a comment

Choose a reason for hiding this comment

Uh oh!

dummdidumm commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

changeset-bot Bot commented Jun 26, 2026 •

edited

Loading

sirkostya009 commented Jun 30, 2026 •

edited

Loading

pkg-svelte-dev Bot commented Jul 1, 2026 •

edited

Loading

dummdidumm commented Jul 2, 2026 •

edited

Loading