fix(unplugin): apply definePage path-param parser overrides (#2699)

posva · web-flow · commit c80748626357 · 2026-05-06T15:31:30.000+02:00
diff --git a/packages/router/src/unplugin/core/customBlock.ts b/packages/router/src/unplugin/core/customBlock.ts
@@ -29,8 +29,16 @@ export interface CustomRouteBlock extends Partial<
   alias?: string[]
 
   params?: {
-    path?: Record<string, string>
+    /**
+     * Override the parser for a given path param. Set to `null` to remove a
+     * filename-based parser (e.g. revert `[id=int]` back to no parser).
+     */
+    path?: Record<string, string | null>
 
+    /**
+     * Declare query params for the route. The value is either a parser name
+     * or an options object with `parser`, `format`, `default`, and `required`.
+     */
     query?: Record<string, string | CustomRouteBlockQueryParamOptions>
   }
 }
diff --git a/packages/router/src/unplugin/core/tree.spec.ts b/packages/router/src/unplugin/core/tree.spec.ts
@@ -1200,6 +1200,63 @@ describe('Tree', () => {
     })
   })
 
+  describe('Path param parsers from definePage', () => {
+    it('applies a parser from definePage to a plain path param', () => {
+      const tree = new PrefixTree(RESOLVED_OPTIONS)
+      const node = tree.insert('events/[when]', 'events/[when].vue')
+
+      node.setCustomRouteBlock('events/[when].vue', {
+        params: { path: { when: 'date' } },
+      })
+
+      expect(node.pathParams).toEqual([
+        expect.objectContaining({ paramName: 'when', parser: 'date' }),
+      ])
+    })
+
+    it('definePage path parser overrides the filename parser', () => {
+      const tree = new PrefixTree(RESOLVED_OPTIONS)
+      const node = tree.insert('events/[when=int]', 'events/[when=int].vue')
+
+      node.setCustomRouteBlock('events/[when=int].vue', {
+        params: { path: { when: 'date' } },
+      })
+
+      expect(node.pathParams[0]).toMatchObject({
+        paramName: 'when',
+        parser: 'date',
+      })
+    })
+
+    it('leaves untouched path params when override only mentions some', () => {
+      const tree = new PrefixTree(RESOLVED_OPTIONS)
+      const node = tree.insert('[a]-[b=int]', '[a]-[b=int].vue')
+
+      node.setCustomRouteBlock('[a]-[b=int].vue', {
+        params: { path: { a: 'date' } },
+      })
+
+      expect(node.pathParams).toEqual([
+        expect.objectContaining({ paramName: 'a', parser: 'date' }),
+        expect.objectContaining({ paramName: 'b', parser: 'int' }),
+      ])
+    })
+
+    it('removes the filename parser when the override is null', () => {
+      const tree = new PrefixTree(RESOLVED_OPTIONS)
+      const node = tree.insert('events/[when=int]', 'events/[when=int].vue')
+
+      node.setCustomRouteBlock('events/[when=int].vue', {
+        params: { path: { when: null } },
+      })
+
+      expect(node.pathParams[0]).toMatchObject({
+        paramName: 'when',
+        parser: null,
+      })
+    })
+  })
+
   describe('_parent convention', () => {
     it('handles _parent.vue as parent component', () => {
       const tree = new PrefixTree(RESOLVED_OPTIONS)
diff --git a/packages/router/src/unplugin/core/treeNodeValue.ts b/packages/router/src/unplugin/core/treeNodeValue.ts
@@ -1,41 +1,19 @@
-import type {
-  CustomRouteBlock,
-  CustomRouteBlockQueryParamOptions,
-} from './customBlock'
+import type { CustomRouteBlock } from './customBlock'
 import { joinPath, mergeRouteRecordOverride, warn } from './utils'
 import { encodePath } from '../utils/encoding'
-import type { RouteRecordRaw } from '../../types'
 
 export const enum TreeNodeType {
   static,
   group,
   param,
 }
 
-export interface RouteRecordOverride extends Partial<
-  Pick<RouteRecordRaw, 'meta' | 'props' | 'path'>
-> {
-  name?: string | undefined | false
-
-  /**
-   * Path aliases.
-   */
-  alias?: string[]
-
-  /**
-   * Param Parsers information.
-   */
-  params?: {
-    path?: Record<string, string>
-
-    query?: Record<string, string | RouteRecordOverrideQueryParamOptions>
-  }
-}
-
-export interface RouteRecordOverrideQueryParamOptions extends CustomRouteBlockQueryParamOptions {
-  default?: string
-  required?: boolean
-}
+/**
+ * Internal merged-overrides shape used by tree nodes. Same structure as
+ * {@link CustomRouteBlock} (the user-facing `<route>` block / `definePage()`
+ * payload).
+ */
+export type RouteRecordOverride = CustomRouteBlock
 
 export type SubSegment = string | TreePathParam
 
@@ -221,7 +199,6 @@ class _TreeNodeValueBase {
    */
   removeOverride(key: keyof CustomRouteBlock) {
     for (const [_filePath, routeBlock] of this._overrides) {
-      // @ts-expect-error
       delete routeBlock[key]
     }
   }
@@ -402,16 +379,47 @@ export const escapeRegex = (str: string): string =>
 export class TreeNodeValueParam extends _TreeNodeValueBase {
   override _type: TreeNodeType.param = TreeNodeType.param
 
+  /**
+   * @param rawSegment The raw segment as defined by the file structure, e.g.
+   * `[id]`, `prefix-[param]-end`, etc.
+   *
+   * @param parent The parent node in the tree, if any.
+   *
+   * @param filenamePathParams Path params parsed from the file segment
+   * (filename convention). The public `pathParams` getter overlays
+   * `definePage()` parser overrides on top of these.
+   *
+   * @param pathSegment The transformed version of the segment into a
+   * vue-router path, e.g. `:id`, `prefix-:param-end`, etc.
+   *
+   * @param subSegments Array of sub segments. This is usually one single
+   * element but can have more for paths like `prefix-[param]-end.vue`.
+   */
   constructor(
     rawSegment: string,
     parent: TreeNodeValue | undefined,
-    public pathParams: TreePathParam[],
+    private filenamePathParams: TreePathParam[],
     pathSegment: string,
     subSegments: SubSegment[]
   ) {
     super(rawSegment, parent, pathSegment, subSegments)
   }
 
+  /**
+   * Path params for this node, with `definePage({ params: { path: ... } })`
+   * parser overrides applied on top of the filename-based parsers.
+   */
+  get pathParams(): TreePathParam[] {
+    const overridePath = this.overrides.params?.path
+    if (!overridePath) return this.filenamePathParams
+    return this.filenamePathParams.map(p =>
+      // an explicit `null` override removes the filename-based parser
+      overridePath[p.paramName] !== undefined
+        ? { ...p, parser: overridePath[p.paramName] }
+        : p
+    )
+  }
+
   // Calculate score for each subsegment to handle mixed static/param parts
   get score(): number[] {
     return this.subSegments.map(segment => {
