fix(shared): suggest :path* subtree form in createRouteMatcher path types by jacekradko · Pull Request #9057 · clerk/javascript

jacekradko · 2026-07-01T03:21:30Z

createRouteMatcher's route-type suggestions now offer /dashboard/:path* instead of /dashboard(.*). (.*) also matches sibling routes like /dashboardxyz; :path* matches only /dashboard and its path-segment subtree. It's a type-level suggestion only (the param is Autocomplete-wrapped), so existing (.*) patterns keep type-checking and there's no runtime change.

Worth a look: the root special-case. WithPathPatternWildcard<'/'> resolves to /:path*, not the naive //:path* (which the vendored path-to-regexp 6.x matches as only /, not everything). I verified /dashboard/:path*, /:path*, and legacy (.*) against the vendored matcher, and @clerk/nextjs typechecks clean against it.

Scoped to the type on purpose: the ['/foo', '/bar(.*)'] JSDoc examples in nextjs/astro/nuxt are left as-is here and can be aligned in a follow-up. The docs are moving to recommend :path* too.

Summary by CodeRabbit

New Features
- Route autocomplete suggestions now prefer the :path* wildcard format for nested paths, making suggested routes more consistent and easier to read.
Bug Fixes
- Improved wildcard route handling for the root path so suggestions avoid invalid double-slash patterns.
- Existing (.*) route patterns continue to work as before.

…ypes WithPathPatternWildcard now suggests `/dashboard/:path*` instead of `/dashboard(.*)`. The `:path*` form matches on path-segment boundaries, so it covers `/dashboard` and its subtree without also matching sibling routes like `/dashboardxyz`. Root is special-cased to `/:path*` to avoid a malformed `//:path*`. Backward compatible: the param is Autocomplete-wrapped, so existing `(.*)` patterns still type-check, and there is no runtime change.

changeset-bot · 2026-07-01T03:21:34Z

🦋 Changeset detected

Latest commit: 42cecb9

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

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

vercel · 2026-07-01T03:21:36Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 1, 2026 3:23am
swingset	Ready	Preview, Comment	Jul 1, 2026 3:23am

coderabbitai · 2026-07-01T03:21:48Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: fa1c58cd-2401-4fd4-812e-f6a5400ac431

📥 Commits

Reviewing files that changed from the base of the PR and between 668b1c8 and 42cecb9.

📒 Files selected for processing (2)

.changeset/path-matcher-segment-wildcard.md
packages/shared/src/pathMatcher.ts

📝 Walkthrough

Walkthrough

This PR modifies the WithPathPatternWildcard type in @clerk/shared to produce :path* subtree-style wildcard suggestions (e.g., /dashboard/:path*) instead of the previous (.*) regex pattern, with a root-path special case. A changeset documents this type-level autocomplete change.

Changes

Path Wildcard Suggestion Update

Layer / File(s)	Summary
Wildcard type and changeset `packages/shared/src/pathMatcher.ts`, `.changeset/path-matcher-segment-wildcard.md`	`WithPathPatternWildcard<T>` now produces `/:path` for root and `${T}/:path` for other paths instead of `${T}(.)`; changeset documents the new autocomplete suggestion behavior while noting existing `(.)` patterns still work.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Poem

A hop, a skip, a tiny tweak,
No more (.*) did I seek,
Now :path* guides the way,
Through dashboards where routes play,
This bunny's type is clean and neat! 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the shared route-type suggestion change to prefer `:path*` in `createRouteMatcher`.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

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

pkg-pr-new · 2026-07-01T03:24:23Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9057

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9057

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9057

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9057

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9057

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9057

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9057

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9057

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9057

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9057

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9057

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9057

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9057

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9057

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9057

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9057

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9057

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9057

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9057

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9057

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9057

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9057

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9057

commit: 42cecb9

github-actions · 2026-07-01T03:24:48Z

API Changes Report

Generated by Break Check on 2026-07-01T03:24:45.738Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	1
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
1 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

🔴 Breaking changes index (1)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/shared	`./pathMatcher`	`WithPathPatternWildcard`

@clerk/shared

Current version: 4.23.0
Recommended bump: MAJOR → 5.0.0

Subpath `./pathMatcher`

🔴 Breaking Changes (1)

Changed: `WithPathPatternWildcard`

- type WithPathPatternWildcard<T = string> = `${T & string}(.*)`;
+ type WithPathPatternWildcard<T = string> = T extends '/' ? '/:path*' : `${T & string}/:path*`;

Static analyzer: Breaking change in type alias WithPathPatternWildcard: Type changed: ${T&string}(.*) → T extends '/' ? '/:path*':${T&string}/:path*``

🤖 AI review (confirmed) (90%): The resolved string literal pattern changed from ${T}(.*) to a conditional type producing /:path* or ${T}/:path*, so any consumer code that matched, compared, or assigned values against the old template literal pattern (e.g. "/foo(.*)") will no longer satisfy the new type.

Migration: Update any hardcoded path strings or type-level usages from the (.*) suffix pattern (e.g. "/foo(.*)") to the new /:path* suffix pattern (e.g. "/foo/:path*" or "/:path*" for root).

Report generated by Break Check

_{Last ran on 42cecb9.}

vercel Bot deployed to Preview – clerk-js-sandbox July 1, 2026 03:22 View deployment

vercel Bot deployed to Preview – swingset July 1, 2026 03:23 View deployment

alexcarpenter approved these changes Jul 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(shared): suggest :path* subtree form in createRouteMatcher path types#9057

fix(shared): suggest :path* subtree form in createRouteMatcher path types#9057
jacekradko wants to merge 1 commit into
mainfrom
jacek/path-matcher-path-star

jacekradko commented Jul 1, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Jul 1, 2026

Uh oh!

vercel Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 1, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

pkg-pr-new Bot commented Jul 1, 2026

Uh oh!

github-actions Bot commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jacekradko commented Jul 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Jul 1, 2026

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Walkthrough

Changes

Uh oh!

pkg-pr-new Bot commented Jul 1, 2026

Uh oh!

github-actions Bot commented Jul 1, 2026

API Changes Report

Summary

🔴 Breaking changes index (1)

@clerk/shared

Subpath ./pathMatcher

🔴 Breaking Changes (1)

Changed: WithPathPatternWildcard

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jacekradko commented Jul 1, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Jul 1, 2026 •

edited

Loading

coderabbitai Bot commented Jul 1, 2026 •

edited

Loading

Subpath `./pathMatcher`

Changed: `WithPathPatternWildcard`