fix(nextjs): Deprecate createRouteMatcher

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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

[Ephem]

Description

Note

For any external folks that stumble across this:

We are about to deprecate createRouteMatcher and 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 createRouteMatcher in @clerk/nextjs, including a runtime warning.

This PR is waiting for:

• Release of the latest eslint-plugin changes
  • We should determine if we also want to release this as stable first - Should be in a good place
• Doc changes to be finalized and released

Doc changes and this PR should go out at roughly the same time.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Deprecations
  • Marked createRouteMatcher() as deprecated and added a runtime warning with migration guidance toward resource-based authorization checks, including a Next.js TypeScript example using auth.protect() to protect pages and server components.
• Tests
  • Added Vitest coverage to verify the deprecation warning is emitted with the expected message when createRouteMatcher() is invoked.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 6, 2026 2:33pm
swingset	Ready	Preview, Comment	Jul 6, 2026 2:33pm

[coderabbitai]

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: 8a2b818b-dc34-4d09-9bfc-5dc8102da8d3

📥 Commits

Reviewing files that changed from the base of the PR and between 938f7a5 and 151e46a.

📒 Files selected for processing (1)

• packages/nextjs/src/server/routeMatcher.ts

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

• packages/nextjs/src/server/routeMatcher.ts

---

📝 Walkthrough

Walkthrough

@clerk/nextjs now warns at runtime when createRouteMatcher() is used. A new changeset documents the deprecation and migration path, and a Vitest test checks the warning call.

Changes

Route matcher deprecation

Layer / File(s)	Summary
Runtime deprecation warning packages/nextjs/src/server/routeMatcher.ts, packages/nextjs/src/server/__tests__/routeMatcher.test.ts, .changeset/nextjs-deprecate-route-matcher.md	createRouteMatcher() now calls the shared deprecation helper with migration text; the new Vitest suite asserts the warning call, and the changeset records the patch deprecation note.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers:alexcarpenter

Poem

A bunny hopped by, ears up high,
to see a route matcher say goodbye.
“Protect the page!” the whiskers cheered,
as deprecation bells appeared.
🐇✨

🚥 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 accurately and concisely summarizes the main change: deprecating createRouteMatcher in nextjs.
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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 151e46a

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-06T14:34:49.123Z

Summary

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

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 151e46a.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/nextjs/src/server/routeMatcher.ts (2)

32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add 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 | 🔵 Trivial

Have Docs review the new deprecation copy.
This @deprecated block 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

📥 Commits

Reviewing files that changed from the base of the PR and between cfd523d and 7f3bbbf.

📒 Files selected for processing (3)

• .changeset/nextjs-deprecate-route-matcher.md
• packages/nextjs/src/server/__tests__/routeMatcher.test.ts
• packages/nextjs/src/server/routeMatcher.ts

[Ephem]

Note: These links need updating if the migration guide moves or is renamed before releasing it

[changeset-bot]

🦋 Changeset detected

Latest commit: 151e46a

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

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	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