feat: typed definePage params.path by posva · Pull Request #2716 · vuejs/router

posva · 2026-05-19T15:36:40Z

Make definePage generic on the SFC's file path so params.path keys are
narrowed to the actual route path-params. The Volar plugin injects the
file path on bare definePage(...) calls, mirroring useRoute().

Codegen emits pathParamNames per file in _RouteFileInfoMap
_RouteFileInfoMap wired through TypesConfig to survive d.ts bundling
Volar plugin escapes apostrophes/backslashes in injected file paths

Summary by CodeRabbit

Release Notes

New Features
- Route parameters now support custom type parsers for stricter type checking
- Enhanced route definition with improved type awareness for file-specific parameters
Improvements
- Strengthened type safety for route parameter validation
- Better IDE support with improved type inference for route configuration

Make `definePage` generic on the SFC's file path so `params.path` keys are narrowed to the actual route path-params. The Volar plugin injects the file path on bare `definePage(...)` calls, mirroring `useRoute()`. - Codegen emits `pathParamNames` per file in `_RouteFileInfoMap` - `_RouteFileInfoMap` wired through `TypesConfig` to survive d.ts bundling - Volar plugin escapes apostrophes/backslashes in injected file paths

netlify · 2026-05-19T15:36:46Z

✅ Deploy Preview for vue-router canceled.

Name	Link
🔨 Latest commit	`3d4ee33`
🔍 Latest deploy log	https://app.netlify.com/projects/vue-router/deploys/6a0c83b2b93b0f0007992c00

pkg-pr-new · 2026-05-19T15:37:14Z

Open in StackBlitz

npm i https://pkg.pr.new/vue-router@2716

commit: dc68515

coderabbitai · 2026-05-19T15:39:40Z

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8e751c9b-fe5c-477e-9b00-845dbe982b34

📥 Commits

Reviewing files that changed from the base of the PR and between db3a6b3 and 3d4ee33.

📒 Files selected for processing (11)

packages/playground-file-based/src/pages/u[name].vue
packages/playground-file-based/src/pages/u[name]/24.vue
packages/playground-file-based/src/routes.d.ts
packages/router/src/experimental/index.ts
packages/router/src/experimental/runtime.ts
packages/router/src/unplugin/codegen/generateDTS.spec.ts
packages/router/src/unplugin/codegen/generateDTS.ts
packages/router/src/unplugin/codegen/generateRouteFileInfoMap.spec.ts
packages/router/src/unplugin/codegen/generateRouteFileInfoMap.ts
packages/router/src/volar/entries/sfc-typed-router.ts
packages/router/vue-router-auto-routes.d.mts

📝 Walkthrough

Walkthrough

The PR extends the Vue Router type system to enable definePage to validate params.path keys against the route file's actual parameters. It introduces _RouteFileInfoMap metadata mapping route files to their path parameter names, generates this metadata for all route files, wires it into TypesConfig, enhances the Volar plugin to inject file paths into definePage calls, and updates the generated types and playground examples.

Changes

Typed definePage path parameters

Layer / File(s)	Summary
Core type infrastructure and contracts `packages/router/vue-router-auto-routes.d.mts`, `packages/router/src/experimental/runtime.ts`, `packages/router/src/experimental/index.ts`	New `_RouteFileInfoMap` interface and generic `definePage<FilePath>` function; `PathParamNamesForFilePath<FilePath>` conditional type derives allowed `params.path` keys from metadata; `DefinePage` interface becomes generic and narrowed.
Route file info metadata code generation `packages/router/src/unplugin/codegen/generateRouteFileInfoMap.ts`, `packages/router/src/unplugin/codegen/generateRouteFileInfoMap.spec.ts`	Codegen traverses route tree and computes `pathParamNames` per file; outputs as sorted deduplicated unions in `_RouteFileInfoMap`; test snapshots validate param ownership rules across static, nested, and multi-param routes.
TypesConfig augmentation wiring `packages/router/src/unplugin/codegen/generateDTS.ts`, `packages/router/src/unplugin/codegen/generateDTS.spec.ts`	Generated `declare module 'vue-router'` now includes `_RouteFileInfoMap` in `TypesConfig`, exposing metadata to type resolver.
Volar plugin definePage enhancement `packages/router/src/volar/entries/sfc-typed-router.ts`	Plugin escapes file path and injects it as a type argument into bare `definePage` calls, narrowing `params.path` keys to the file's route parameters.
Generated types and playground examples `packages/playground-file-based/src/routes.d.ts`, `packages/playground-file-based/src/pages/u[name].vue`, `packages/playground-file-based/src/pages/u[name]/24.vue`	Generated `_RouteFileInfoMap` populated with `pathParamNames` for all route files; example pages updated to use `definePage` with typed `params.path` constraints.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

vuejs/router#2700: Extends TypesConfig wiring in generated declarations; related concurrent work on module augmentation infrastructure.
vuejs/router#2607: Modifies sfc-typed-router.ts Volar plugin to enhance useRoute() and definePage() call analysis; directly related to file-path escaping and type injection.
vuejs/router#2699: Implements definePage path-param parser overrides aligned with this PR's PathParamNamesForFilePath typing plumbing.

Suggested labels

💥 breaking change

Poem

🐰 The humble param now knows its place,

By file and path it finds its case,

When definePage is called with care,

The Volar sprite injects the air,

Of typed suggestions, crisp and true,

Safe params shine in emerald blue! 🌳

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: typed definePage params.path' directly and precisely describes the main feature: making definePage's params.path property typed based on the SFC file path.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/define-page-typed-path-params

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

posva added 5 commits May 19, 2026 17:00

refactor: simpler type

8cdcc17

refactor: simplify code

8691e26

refactor: definePage can only change own page params

943e8c7

test: extra one

dc68515

chore: unused test [skip ci]

3d4ee33

posva merged commit d65de74 into main May 19, 2026
4 of 5 checks passed

posva deleted the feat/define-page-typed-path-params branch May 19, 2026 15:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: typed definePage params.path#2716

feat: typed definePage params.path#2716
posva merged 6 commits into
mainfrom
feat/define-page-typed-path-params

posva commented May 19, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

netlify Bot commented May 19, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented May 19, 2026

Uh oh!

coderabbitai Bot commented May 19, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

posva commented May 19, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Release Notes

Uh oh!

netlify Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vue-router canceled.

Uh oh!

pkg-pr-new Bot commented May 19, 2026

Uh oh!

coderabbitai Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

posva commented May 19, 2026 •

edited by coderabbitai Bot

Loading

netlify Bot commented May 19, 2026 •

edited

Loading

coderabbitai Bot commented May 19, 2026 •

edited

Loading