Select protected middleware routes
A middleware needs to apply authentication protection only to selected dashboard or API paths.
Clerk · Function
createRouteMatcher
createRouteMatcher() builds a predicate from an array of Next.js-style route patterns. Calling the predicate with a middleware request returns true when the request matches a supplied route; Clerk now marks the helper deprecated.
How it works
Pass an array of Next.js-style route patterns to createRouteMatcher. It returns a predicate that accepts the middleware request and returns true when the request path matches one of those patterns, allowing middleware logic such as auth.protect() to run conditionally.
Syntax
createRouteMatcher(routes: string[]): (req: Request) => booleanParameters
| Name | Type | Description |
|---|---|---|
routes | string[] | An array of route patterns using Next.js Middleware matcher-style syntax. |
Returns
A function that accepts the Next.js Middleware req object and returns true when its route matches one of the supplied patterns.
Key points
- Provide multiple route patterns in one array; the resulting predicate tests whether the requested route matches any of them.
- The returned function takes the Next.js middleware req object and produces a boolean match result.
- Route patterns follow Next.js Middleware matcher syntax.
- The :path* wildcard is the preferred representation for matching all descendants of a route.
Common mistakes
- The helper is deprecated, emits a runtime warning, and is scheduled for removal in the next major version; prefer resource-based auth checks.
- For a route subtree, use the :path* pattern such as /dashboard/:path* rather than the older /dashboard(.*) form.
- Do not use this helper for non-authentication path logic; use Next.js native matching instead.
Example: Protect dashboard routes
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isDashboardRoute = createRouteMatcher(['/dashboard/:path*'])
export default clerkMiddleware(async (auth, req) => {
if (isDashboardRoute(req)) {
await auth.protect()
}
})Creates a predicate for dashboard paths and protects matching requests in Clerk middleware.
When to use it
Group route patterns
Several related paths need to share one route predicate.
Interview questions
QWhat does createRouteMatcher return?
It accepts an array of route patterns and returns a function. Calling that function with the middleware request returns true when the request matches any supplied pattern.
Follow-up: How should a dashboard subtree be represented? Use /dashboard/:path*, which maps directly to router path-segment matching.
QWhat format do its route patterns use?
The patterns use the same format as paths supplied to the Next.js Middleware matcher. This lets one predicate cover several route patterns.
Follow-up: What should be used for non-authentication path decisions? Use the framework's native matcher and req.nextUrl.pathname.
QHow was the matcher typically used with Clerk authentication?
It was commonly used inside clerkMiddleware() to conditionally call authentication protection for matching requests. Current Clerk guidance recommends protecting each server-side resource instead of relying on middleware-based auth checks.
Follow-up: What migration direction should a new implementation follow? Move checks into the individual page, Route Handler, Server Function, or Server Action that accesses protected data.
Related
clerkMiddlewareauth.protectconfig.matcherreq.nextUrl.pathname