createRouteMatcher migration guide + eslint-plugin docs

[Ephem]

Builds on and is targeted at: #3426

Important

This does not represent a PR that is ready to merge to main. My intent is to merge it into #3426

That PR represents what we will finally merge for the createRouteMatcher deprecation and will require more work.

🔎 Previews:

• https://clerk.com/docs/pr/fredrik-crm-migration-guide/guides/development/upgrading/upgrade-guides/migrating-from-create-route-matcher
• https://clerk.com/docs/pr/fredrik-crm-migration-guide/reference/nextjs/eslint-plugin
• https://clerk.com/docs/pr/fredrik-crm-migration-guide/reference/nextjs/clerk-middleware

What does this solve? What changed?

• Moves createRouteMatcher docs to the bottom of the clerkMiddleware reference
• Rewrites the createRouteMatcher() migration guide and moves it to the Upgrades section
  • Now includes two paths, one for when using the lint rule, one manual flow
• Adds a reference page for the eslint rule

Note that in contrast to #3426 I decided to include the wording that createRouteMatcher is deprecated here, as I know expect that deprecation to land first, with these docs as an immediate follow-up.

Deadline

Other resources

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Jun 25, 2026 8:34pm

[Ephem]

If this URL changes, this PR also needs updating: clerk/javascript#8994

[alexisintech]

Posted my docs review! The largest updates were:

eslint-plugin.mdx

• Rewrote the intro paragraph to lead with what the rule actually does (flags server-side resources missing an authentication check) and surface the Bulk Fixer CLI up front. Dropped the "resources in protected folders guard themselves" framing — too much undefined jargon for the opener.
• Reorganized the sections into ## Setup and ## How the rule works and ## Bulk Fixer CLI
  • New _partials/nextjs/bulk-fixer-cli.mdx — shared between the reference doc and the migration guide.
• Tightened terminology — "protection" is overloaded (it's the rule name, the config key protected, and auth.protect()), so I replaced the loose abstract uses with "authentication check" where it added clarity.

migrating-from-create-route-matcher.mdx

• Punchier intro paragraph that explicitly contrasts old vs new ("Previously… Clerk is deprecating…").
• Added tabs for "Incremental migration" vs "Migrate whole application at once"
  • New _partials/preserve-signed-out-ux.mdx used in both migration tabs.
• New _partials/nextjs/bulk-fixer-cli.mdx — shared between the reference doc and the migration guide.
• Clarified the "verify Server Functions first" callout with the actual reason — they're called by ID, not by path, so Middleware patterns can't reliably cover them.
• Fixed a copy-paste leak in the manual tab's "Test and repeat" step that told readers to "add more patterns to the lint rule" even though that tab doesn't use the rule.
• Terminology consistency with the reference doc (Client Components "can't reach privileged data directly" instead of "by themselves"; "external API endpoints" to disambiguate from Route Handlers).