fix(nextjs): Deprecate createRouteMatcher#8994
Open
Ephem wants to merge 1 commit into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthrough
ChangesRoute matcher deprecation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
Comment |
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
Contributor
API Changes Report
Summary
No API Changes DetectedAll packages have stable APIs with no detected changes. Report generated by Break Check Last ran on |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
packages/nextjs/src/server/routeMatcher.ts (2)
32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd an explicit return type to the exported factory.
This public API should declare its return type explicitly to match the TypeScript guidelines for exported functions and keep the surface stable for consumers. As per coding guidelines and the retrieved learning, exported TypeScript APIs should declare explicit return types.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/nextjs/src/server/routeMatcher.ts` at line 32, The exported factory createRouteMatcher currently relies on type inference for its public API; add an explicit return type annotation to the createRouteMatcher function signature so the route matcher surface stays stable for consumers and matches the TypeScript guideline for exported functions. Keep the implementation unchanged and ensure the declared return type reflects the value returned by createRouteMatcher.Sources: Coding guidelines, Learnings
23-31: 📐 Maintainability & Code Quality | 🔵 TrivialHave Docs review the new deprecation copy.
This@deprecatedblock will render in generated Clerk Docs, so the migration wording should be reviewed before release. As per path instructions, public/reference-facing JSDoc is customer-facing documentation.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/nextjs/src/server/routeMatcher.ts` around lines 23 - 31, The `@deprecated` JSDoc in routeMatcher is customer-facing and will be rendered in the generated docs, so the migration copy needs a docs review before release. Have Docs review and approve the wording in the routeMatcher deprecation block, especially the guidance about moving auth checks into pages/layouts/API routes/Server Functions and the migration guide link, and make any requested copy edits without changing the API behavior.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@packages/nextjs/src/server/routeMatcher.ts`:
- Line 32: The exported factory createRouteMatcher currently relies on type
inference for its public API; add an explicit return type annotation to the
createRouteMatcher function signature so the route matcher surface stays stable
for consumers and matches the TypeScript guideline for exported functions. Keep
the implementation unchanged and ensure the declared return type reflects the
value returned by createRouteMatcher.
- Around line 23-31: The `@deprecated` JSDoc in routeMatcher is customer-facing
and will be rendered in the generated docs, so the migration copy needs a docs
review before release. Have Docs review and approve the wording in the
routeMatcher deprecation block, especially the guidance about moving auth checks
into pages/layouts/API routes/Server Functions and the migration guide link, and
make any requested copy edits without changing the API behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 0bf23da2-670c-48f3-a91c-8cb1a5356bbd
📒 Files selected for processing (3)
.changeset/nextjs-deprecate-route-matcher.mdpackages/nextjs/src/server/__tests__/routeMatcher.test.tspackages/nextjs/src/server/routeMatcher.ts
Ephem
commented
Jun 25, 2026
| Middleware-based auth checks rely on path matching, which can diverge from how Next.js routes requests and leave protected resources reachable. | ||
|
|
||
| For a migration guide, see: | ||
| https://clerk.com/docs/guides/development/upgrading/upgrade-guides/migrating-from-create-route-matcher |
Member
Author
There was a problem hiding this comment.
Note: These links need updating if the migration guide moves or is renamed before releasing it
jacekradko
approved these changes
Jun 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Note
For any external folks that stumble across this:
We are about to deprecate
createRouteMatcherand are recommending not doing auth gating at the Middleware level. Middleware-based auth checks rely on path matching, which can diverge from how Next.js routes requests and leave protected resources reachable.We are launching a lint rule to help you ensure you protect all relevant individual resources.
Full rationale and a migration guide will be available before we merge this.
Deprecates
createRouteMatcherin@clerk/nextjs, including a runtime warning.This PR is waiting for:
Doc changes and this PR should go out at roughly the same time.
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
createRouteMatcher()with guidance to use resource-based authorization checks instead.