feat: custom param name

[PindaPixel]

I've been giving the param matchers a try and they're absolutely great!

Context for this change: I use kebab case to define my param matchers, but that breaks the types since there can be no dashes in type names. Personally I'd like to use this to convert the name to camel case.

Summary by CodeRabbit

• New Features
  • Parameter parsers now support customizable name generation via configuration, letting you override how parser names are derived while preserving the existing default behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds an optional getName hook to param parser options and updates internal context logic to use a local getParamParserName helper (falling back to parsePathe(file).name) when discovering and watching param parser files.

Changes

Cohort / File(s)	Summary
Options: param parser naming src/options.ts	Adds getName(file: string) => string to ParamParsersOptions and sets getName: undefined in DEFAULT_PARAM_PARSERS_OPTIONS.
Context: param parser resolution & watcher src/core/context.ts	Introduces internal getParamParserName that uses options.experimental.paramParsers?.getName or falls back to parsePathe(file).name; replaces direct parsePathe(file).name usages during initial scan and watcher add/unlink handlers.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: custom param name' directly aligns with the PR's main objective of allowing custom parameter names for param matchers.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 57ff4be and 2cc9bc4.

📒 Files selected for processing (1)

• src/core/context.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/core/context.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: test

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

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

commit: 2cc9bc4

[codecov]

Codecov Report

❌ Patch coverage is 20.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.04%. Comparing base (73d02c0) to head (2cc9bc4).

Files with missing lines	Patch %	Lines
src/core/context.ts	20.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #774      +/-   ##
==========================================
- Coverage   73.06%   73.04%   -0.02%     
==========================================
  Files          30       30              
  Lines        2421     2423       +2     
  Branches      847      849       +2     
==========================================
+ Hits         1769     1770       +1     
- Misses        545      546       +1     
  Partials      107      107              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/core/context.ts (1)

220-238: Critical: Watcher must use custom getName function.

The watcher doesn't use the custom getName function, only the initial scan does. This creates inconsistent naming:

• Initial scan uses custom getName (lines 136-139)
• Watcher 'add' uses default parsePathe(file).name (line 224)
• Watcher 'unlink' uses default parsePathe(file).name (line 235)

This breaks the feature when files are added/removed after startup.

🔎 Proposed fix

  function setupParamParserWatcher(watcher: FSWatcher, cwd: string) {
    logger.log(`🤖 Scanning param parsers in ${cwd}`)
+   const getName =
+     options.experimental.paramParsers?.getName ||
+     ((file: string) => parsePathe(file).name)
    return watcher
      .on('add', (file) => {
-       const name = parsePathe(file).name
+       const name = getName(file)
        const absolutePath = resolve(cwd, file)
        paramParsersMap.set(name, {
          name,
          typeName: `Param_${name}`,
          absolutePath,
          relativePath: './' + relative(options.root, absolutePath),
        })
        writeConfigFiles()
      })
      .on('unlink', (file) => {
-       paramParsersMap.delete(parsePathe(file).name)
+       paramParsersMap.delete(getName(file))
        writeConfigFiles()
      })
  }

🧹 Nitpick comments (1)

src/options.ts (1)

246-251: Minor documentation inconsistency.

The JSDoc references path.parse(file).name but the actual implementation uses parsePathe(file).name. Consider updating the documentation for consistency.

🔎 Proposed documentation fix

  /**
   * Method to generate the name of the param matcher.
   *
-  * @default `(file) => path.parse(file).name`
+  * @default `(file) => parsePathe(file).name`
   */
  getName?: (file: string) => string

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 73d02c0 and 57ff4be.

📒 Files selected for processing (2)

• src/core/context.ts
• src/options.ts

🧰 Additional context used

🧠 Learnings (4)

📚 Learning: 2025-08-23T12:54:44.918Z

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/core/context.ts:109-150
Timestamp: 2025-08-23T12:54:44.918Z
Learning: In src/core/context.ts, when paramParsers is defined in resolved options, the dir property is guaranteed to be an array, so optional chaining on options.experimental.paramParsers?.dir.map() is sufficient protection against undefined values.

Applied to files:

• src/core/context.ts
• src/options.ts

📚 Learning: 2025-08-23T12:50:36.614Z

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/core/context.ts:137-142
Timestamp: 2025-08-23T12:50:36.614Z
Learning: In src/core/context.ts, param parser relative paths must be computed relative to options.root (not relative to DTS file location) and the './' prefix is required for proper path resolution in the generated code.

Applied to files:

• src/core/context.ts
• src/options.ts

📚 Learning: 2025-08-16T13:00:51.271Z

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/core/context.ts:109-147
Timestamp: 2025-08-16T13:00:51.271Z
Learning: In src/core/context.ts, the options parameter is already resolved, meaning options.experimental.paramMatchers is either an object with a dir property or undefined - never a boolean. The boolean normalization happens earlier in the options resolution phase.

Applied to files:

• src/core/context.ts
• src/options.ts

📚 Learning: 2025-08-16T13:01:42.709Z

Learnt from: posva
Repo: posva/unplugin-vue-router PR: 700
File: src/codegen/generateParamParsers.ts:91-94
Timestamp: 2025-08-16T13:01:42.709Z
Learning: In the unplugin-vue-router codebase, path normalization for import specifiers is handled elsewhere in the system (not at individual call sites like generateParamParsers.ts). Individual functions should not normalize paths themselves as it violates separation of concerns.

Applied to files:

• src/core/context.ts

🧬 Code graph analysis (1)

src/core/context.ts (2)

src/core/tree.ts (1)

• name (269-276)

src/core/extendRoutes.ts (2)

• name (90-92)
• name (97-99)

🔇 Additional comments (2)

src/options.ts (1)

254-257: LGTM!

The default value correctly reflects the optional nature of the getName property, with the fallback implementation properly handled in context.ts.

src/core/context.ts (1)

136-139: LGTM!

The implementation correctly uses the custom getName function with proper fallback to parsePathe(file).name.