From 7e23db2e17accd023ff24e168329d24dea0c1407 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 27 Jul 2026 11:58:57 -0700
Subject: [PATCH 1/4] chore(nuxt): Remove createRouteMatcher support

---
 .changeset/major-nuxt-remove-route-matcher.md |  66 +++++++
 .../nuxt-node/app/middleware/auth.global.js   |  16 --
 .../nuxt-node/app/middleware/auth.js          |   7 +
 .../app/pages/user-profile/[...slug].vue      |   2 +
 integration/tests/nuxt/middleware.test.ts     | 163 +++++-------------
 packages/nuxt/src/module.ts                   |   4 -
 .../client/__tests__/routeMatcher.test.ts     |  26 ---
 packages/nuxt/src/runtime/client/index.ts     |   1 -
 .../nuxt/src/runtime/client/routeMatcher.ts   |  43 -----
 .../server/__tests__/clerkMiddleware.test.ts  |   9 +-
 .../server/__tests__/routeMatcher.test.ts     |  31 ----
 packages/nuxt/src/runtime/server/index.ts     |   1 -
 .../nuxt/src/runtime/server/routeMatcher.ts   |  47 -----
 13 files changed, 124 insertions(+), 292 deletions(-)
 create mode 100644 .changeset/major-nuxt-remove-route-matcher.md
 delete mode 100644 integration/templates/nuxt-node/app/middleware/auth.global.js
 create mode 100644 integration/templates/nuxt-node/app/middleware/auth.js
 delete mode 100644 packages/nuxt/src/runtime/client/__tests__/routeMatcher.test.ts
 delete mode 100644 packages/nuxt/src/runtime/client/routeMatcher.ts
 delete mode 100644 packages/nuxt/src/runtime/server/__tests__/routeMatcher.test.ts
 delete mode 100644 packages/nuxt/src/runtime/server/routeMatcher.ts

diff --git a/.changeset/major-nuxt-remove-route-matcher.md b/.changeset/major-nuxt-remove-route-matcher.md
new file mode 100644
index 00000000000..5579947104e
--- /dev/null
+++ b/.changeset/major-nuxt-remove-route-matcher.md
@@ -0,0 +1,66 @@
+---
+'@clerk/nuxt': major
+---
+
+Remove `createRouteMatcher` from `@clerk/nuxt/server` and the auto-imported client-side `createRouteMatcher`. Middleware-based auth checks rely on path matching, which can diverge from how requests are actually routed and leave protected resources reachable. Move auth checks into the resources themselves.
+
+Protect API routes inside the event handler itself:
+
+```ts
+export default defineEventHandler(event => {
+  const { userId } = event.context.auth();
+
+  if (!userId) {
+    throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
+  }
+
+  return { userId };
+});
+```
+
+Protect pages with a named route middleware and opt pages into it with `definePageMeta()`. Child routes inherit the middleware applied to their parent, so a single declaration can protect a whole section:
+
+```ts
+// app/middleware/auth.ts
+export default defineNuxtRouteMiddleware(() => {
+  const { isSignedIn } = useAuth();
+
+  if (!isSignedIn.value) {
+    return navigateTo('/sign-in');
+  }
+});
+```
+
+```vue
+<script setup>
+definePageMeta({ middleware: 'auth' });
+</script>
+```
+
+If you want to hand this work to a coding agent, use this migration prompt:
+
+```md
+Migrate my Nuxt project away from Clerk's removed `createRouteMatcher` API.
+
+1. Find every matcher created with `createRouteMatcher`, along with the logic
+   that uses it (throwing 401 errors, calling `navigateTo('/sign-in')`, etc.).
+   Matchers can appear in Nitro server middleware (imported from
+   `@clerk/nuxt/server`) or in Nuxt route middleware (auto-imported).
+2. For every API route those matchers protected, move the auth check into the
+   event handler itself:
+   const { userId } = event.context.auth();
+   if (!userId) throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
+   Keep any role or permission checks (`event.context.auth().has(...)`) with
+   the resource as well.
+3. For every page those matchers protected, create a named route middleware in
+   `app/middleware/` that checks `useAuth()` and redirects with `navigateTo()`,
+   then opt pages into it with `definePageMeta({ middleware: 'auth' })`. Child
+   routes inherit the middleware applied to their parent.
+4. Remove the `createRouteMatcher` imports and calls. Keep `clerkMiddleware()`
+   itself. Middleware logic unrelated to auth protection (headers, locale
+   redirects, etc.) may stay, using plain `getRequestURL(event).pathname`
+   checks.
+5. Make sure every route previously covered by a matcher pattern (including
+   glob patterns like `/dashboard(.*)`) now has its own check, then verify the
+   project builds.
+```
diff --git a/integration/templates/nuxt-node/app/middleware/auth.global.js b/integration/templates/nuxt-node/app/middleware/auth.global.js
deleted file mode 100644
index 0e6f082773b..00000000000
--- a/integration/templates/nuxt-node/app/middleware/auth.global.js
+++ /dev/null
@@ -1,16 +0,0 @@
-export default defineNuxtRouteMiddleware(to => {
-  const { userId } = useAuth();
-
-  const isPublicPage = createRouteMatcher(['/sign-in(.*)', '/sign-up(.*)']);
-  const isProtectedPage = createRouteMatcher(['/user-profile(.*)']);
-
-  // Is authenticated and trying to access a public page
-  if (userId.value && isPublicPage(to)) {
-    return navigateTo('/user-profile');
-  }
-
-  // Is not authenticated and trying to access a protected page
-  if (!userId.value && isProtectedPage(to)) {
-    return navigateTo('/sign-in');
-  }
-});
diff --git a/integration/templates/nuxt-node/app/middleware/auth.js b/integration/templates/nuxt-node/app/middleware/auth.js
new file mode 100644
index 00000000000..3ef9b853669
--- /dev/null
+++ b/integration/templates/nuxt-node/app/middleware/auth.js
@@ -0,0 +1,7 @@
+export default defineNuxtRouteMiddleware(() => {
+  const { isSignedIn } = useAuth();
+
+  if (!isSignedIn.value) {
+    return navigateTo('/sign-in');
+  }
+});
diff --git a/integration/templates/nuxt-node/app/pages/user-profile/[...slug].vue b/integration/templates/nuxt-node/app/pages/user-profile/[...slug].vue
index bc5be9d7d67..03dcb56f95b 100644
--- a/integration/templates/nuxt-node/app/pages/user-profile/[...slug].vue
+++ b/integration/templates/nuxt-node/app/pages/user-profile/[...slug].vue
@@ -1,4 +1,6 @@
 <script setup>
+definePageMeta({ middleware: 'auth' });
+
 const { data: user } = await useFetch('/api/me');
 </script>
 
diff --git a/integration/tests/nuxt/middleware.test.ts b/integration/tests/nuxt/middleware.test.ts
index 9b6e58a7a47..b12eb269a33 100644
--- a/integration/tests/nuxt/middleware.test.ts
+++ b/integration/tests/nuxt/middleware.test.ts
@@ -14,23 +14,21 @@ const nuxtConfigFile = () => `export default defineNuxtConfig({
           }
         });`;
 
-const clerkMiddlewareFile = () => `import { clerkMiddleware, createRouteMatcher } from '@clerk/nuxt/server';
+const clerkMiddlewareFile = () => `import { clerkMiddleware } from '@clerk/nuxt/server';
 
-        const isProtectedRoute = createRouteMatcher(['/api/me', '/api/admin(.*)']);
+        export default clerkMiddleware();
+      `;
 
-        export default clerkMiddleware((event) => {
+const adminApiRouteFile = () => `export default defineEventHandler((event) => {
           const { userId } = event.context.auth();
 
-          if (!userId && isProtectedRoute(event)) {
+          if (!userId) {
             throw createError({
               statusCode: 401,
               statusMessage: 'You are not authorized to access this resource.'
             })
           }
-        });
-      `;
 
-const adminApiRouteFile = () => `export default defineEventHandler((event) => {
           return { status: 'ok' };
         });`;
 
@@ -44,7 +42,37 @@ const mePageFile = () => `<script setup>
           <div v-else>Unknown status</div>
         </template>`;
 
-test.describe('custom middleware @nuxt', () => {
+// Paths using URL encoding tricks that historically diverged between
+// middleware path matching and Nitro's routing normalization. With the auth
+// check on the event handler itself, the exact router outcome (401 vs 404 vs
+// 400) is Nitro's business; what must always hold is that none of these serve
+// the protected resource.
+const trickPaths = [
+  // percent-encoded characters resolving to the protected path
+  '/api/%61dmin/users',
+  '/api/a%64min/users',
+  // double-encoded
+  '/api/%2561dmin/users',
+  // encoded slash is not a path separator
+  '/api%2Fadmin/users',
+  // null byte
+  '/api/admin%00/users',
+  // malformed percent-encoding
+  '/api/%zz/users',
+  // encoded dot segments and traversal
+  '/api/%2e/admin/users',
+  '/api/%2e%2e/admin/users',
+  '/api/foo/%2e%2e/admin/users',
+  // fully encoded './' and '../'
+  '/api%2f%2e%2fadmin/users',
+  '/api%2f%2e%2e%2fadmin/users',
+  '/api/foo%2f%2e%2e%2fadmin/users',
+  // double slashes
+  '//api/admin/users',
+  '/api//admin/users',
+];
+
+test.describe('resource-based route protection @nuxt', () => {
   test.describe.configure({ mode: 'serial' });
   let app: Application;
 
@@ -69,7 +97,7 @@ test.describe('custom middleware @nuxt', () => {
     await app.teardown();
   });
 
-  test('guard API route with custom middleware', async ({ page, context }) => {
+  test('guard API route with resource-based auth check', async ({ page, context }) => {
     const u = createTestUtils({ app, page, context });
     const fakeUser = u.services.users.createFakeUser();
     await u.services.users.createBapiUser(fakeUser);
@@ -78,7 +106,7 @@ test.describe('custom middleware @nuxt', () => {
     await u.page.goToAppHome();
     await u.po.expect.toBeSignedOut();
     await u.page.goToRelative('/me');
-    await expect(u.page.getByText('401: You are not authorized to access this resource')).toBeVisible();
+    await expect(u.page.getByText('401: Unauthorized')).toBeVisible();
 
     // Sign in flow
     await u.page.goToRelative('/sign-in');
@@ -93,117 +121,16 @@ test.describe('custom middleware @nuxt', () => {
 
     await fakeUser.deleteIfExists();
   });
-});
-
-test.describe('percent-encoded URL handling @nuxt', () => {
-  test.describe.configure({ mode: 'serial' });
-  let app: Application;
-
-  test.beforeAll(async () => {
-    test.setTimeout(90_000);
-    app = await appConfigs.nuxt.node
-      .clone()
-      .setName('nuxt-custom-middleware')
-      .addFile('nuxt.config.js', nuxtConfigFile)
-      .addFile('server/middleware/clerk.js', clerkMiddlewareFile)
-      .addFile('server/api/admin/[...action].js', adminApiRouteFile)
-      .commit();
-
-    await app.setup();
-    // pkglab installs with --ignore-scripts, so nuxt prepare must be run manually
-    execSync('npx nuxt prepare', { cwd: app.appDir, stdio: 'pipe' });
-    await app.withEnv(appConfigs.envs.withCustomRoles);
-    await app.dev();
-  });
 
-  test.afterAll(async () => {
-    await app.teardown();
-  });
-
-  test('handle percent-encoded URL on protected routes', async () => {
-    const normalRes = await fetch(app.serverUrl + '/api/admin/users');
-    expect(normalRes.status).toBe(401);
-
-    // %61 = 'a': /api/%61dmin/users decodes to /api/admin/users
-    const encodedRes = await fetch(app.serverUrl + '/api/%61dmin/users');
-    expect(encodedRes.status).toBe(401);
-
-    // %64 = 'd': /api/a%64min/users decodes to /api/admin/users
-    const encodedRes2 = await fetch(app.serverUrl + '/api/a%64min/users');
-    expect(encodedRes2.status).toBe(401);
-  });
-
-  test('double-encoded URLs do not match route (Nitro router rejects)', async () => {
-    // %2561 decodes one layer to %61 — Nitro's file-based router does not
-    // match %2561dmin to the admin/ directory, returning 404
-    const res = await fetch(app.serverUrl + '/api/%2561dmin/users');
-    expect(res.status).toBe(404);
-  });
-
-  test('encoded slash is not decoded into a path separator', async () => {
-    // %2F is a reserved delimiter — decodeURI preserves it, so the matcher
-    // sees /api%2Fadmin/users which does not match /api/admin(.*).
-    // The router also treats %2F as a literal segment char, not a separator.
-    const res = await fetch(app.serverUrl + '/api%2Fadmin/users');
-    expect(res.status).not.toBe(200);
-  });
-
-  test('null byte in path is caught by middleware as protected route', async () => {
-    // %00 decodes to a null char — /api/admin\0/users still matches
-    // /api/admin(.*) so our middleware correctly blocks it with 401
-    const res = await fetch(app.serverUrl + '/api/admin%00/users');
+  test('protected API route returns 401 when signed out', async () => {
+    const res = await fetch(app.serverUrl + '/api/admin/users');
     expect(res.status).toBe(401);
   });
 
-  test('malformed percent-encoding returns 400 (clerkMiddleware catches MalformedURLError)', async () => {
-    // %zz is not valid percent-encoding — createPathMatcher throws
-    // MalformedURLError, which clerkMiddleware catches and returns 400
-    const res = await fetch(app.serverUrl + '/api/%zz/users');
-    expect(res.status).toBe(400);
-  });
-
-  test('encoded dot-current segment is caught by middleware', async () => {
-    // %2e = '.' — /api/%2e/admin/users resolves to /api/./admin/users → /api/admin/users
-    // Our middleware matches the resolved path as protected
-    const res = await fetch(app.serverUrl + '/api/%2e/admin/users');
-    expect(res.status).toBe(401);
-  });
-
-  test('encoded dot-parent segment does not reach protected route', async () => {
-    // %2e%2e = '..' — /api/%2e%2e/admin/users resolves to /api/../admin/users → /admin/users
-    // Nitro's router does not match this to any route, returning 404
-    const res = await fetch(app.serverUrl + '/api/%2e%2e/admin/users');
-    expect(res.status).toBe(404);
-  });
-
-  test('encoded dot-parent traversal through fake segment is caught by middleware', async () => {
-    // /api/foo/%2e%2e/admin/users resolves to /api/foo/../admin/users → /api/admin/users
-    // Our middleware matches the resolved path as protected, returning 401
-    const res = await fetch(app.serverUrl + '/api/foo/%2e%2e/admin/users');
-    expect(res.status).toBe(401);
-  });
-
-  test('fully encoded dot segments with encoded slash are rejected (Nitro rejects)', async () => {
-    // %2e%2f = './', %2e%2e%2f = '../' — when the slash is also encoded,
-    // Nitro treats the entire sequence as a single path segment and
-    // doesn't match any route, returning 404
-    const dotSlashCurrent = await fetch(app.serverUrl + '/api%2f%2e%2fadmin/users');
-    expect(dotSlashCurrent.status).toBe(404);
-
-    const dotSlashParent = await fetch(app.serverUrl + '/api%2f%2e%2e%2fadmin/users');
-    expect(dotSlashParent.status).toBe(404);
-
-    const dotSlashTraversal = await fetch(app.serverUrl + '/api/foo%2f%2e%2e%2fadmin/users');
-    expect(dotSlashTraversal.status).toBe(404);
-  });
-
-  test('double slashes cannot bypass protected route', async () => {
-    // Double slashes before the protected segment
-    const res1 = await fetch(app.serverUrl + '//api/admin/users');
-    expect(res1.status).not.toBe(200);
-
-    // Double slashes in the middle of the path
-    const res2 = await fetch(app.serverUrl + '/api//admin/users');
-    expect(res2.status).not.toBe(200);
+  test('no URL encoding trick can access the protected route', async () => {
+    for (const path of trickPaths) {
+      const res = await fetch(app.serverUrl + path);
+      expect(res.status, `expected non-200 for ${path}`).not.toBe(200);
+    }
   });
 });
diff --git a/packages/nuxt/src/module.ts b/packages/nuxt/src/module.ts
index 897b2ff9f03..07eca1118ab 100644
--- a/packages/nuxt/src/module.ts
+++ b/packages/nuxt/src/module.ts
@@ -134,10 +134,6 @@ export default defineNuxtModule<ModuleOptions>({
     // Add auto-imports for Clerk components, composables and client utils
     addImportsDir(resolver.resolve('./runtime/composables'));
     addImports([
-      {
-        name: 'createRouteMatcher',
-        from: resolver.resolve('./runtime/client'),
-      },
       {
         name: 'updateClerkOptions',
         from: resolver.resolve('./runtime/client'),
diff --git a/packages/nuxt/src/runtime/client/__tests__/routeMatcher.test.ts b/packages/nuxt/src/runtime/client/__tests__/routeMatcher.test.ts
deleted file mode 100644
index 7fd4551311c..00000000000
--- a/packages/nuxt/src/runtime/client/__tests__/routeMatcher.test.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { createRouteMatcher } from '../routeMatcher';
-
-const { mockDeprecated } = vi.hoisted(() => ({
-  mockDeprecated: vi.fn(),
-}));
-
-vi.mock('@clerk/shared/deprecated', () => ({
-  deprecated: mockDeprecated,
-}));
-
-describe('createRouteMatcher', () => {
-  beforeEach(() => {
-    mockDeprecated.mockClear();
-  });
-
-  it('should emit a deprecation warning when called', () => {
-    createRouteMatcher(['/dashboard(.*)']);
-
-    expect(mockDeprecated).toHaveBeenCalledWith(
-      'createRouteMatcher',
-      "Use Nuxt's built-in route middleware to protect pages instead: create a named middleware that checks the user's authentication status and opt pages into it with `definePageMeta({ middleware: 'auth' })`.",
-    );
-  });
-});
diff --git a/packages/nuxt/src/runtime/client/index.ts b/packages/nuxt/src/runtime/client/index.ts
index 424c99be18e..3c1da3d939f 100644
--- a/packages/nuxt/src/runtime/client/index.ts
+++ b/packages/nuxt/src/runtime/client/index.ts
@@ -1,3 +1,2 @@
-export { createRouteMatcher } from './routeMatcher';
 export { updateClerkOptions } from '@clerk/vue';
 export { getToken } from '@clerk/shared/getToken';
diff --git a/packages/nuxt/src/runtime/client/routeMatcher.ts b/packages/nuxt/src/runtime/client/routeMatcher.ts
deleted file mode 100644
index 1758f1f5002..00000000000
--- a/packages/nuxt/src/runtime/client/routeMatcher.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { deprecated } from '@clerk/shared/deprecated';
-import { createPathMatcher, type PathMatcherParam } from '@clerk/shared/pathMatcher';
-import type { RouteMiddleware } from 'nuxt/app';
-
-type RouteLocation = Parameters<RouteMiddleware>[0];
-
-export type RouteMatcherParam = PathMatcherParam;
-
-/**
- * `createRouteMatcher` is a Clerk helper function that allows you to protect multiple routes. It accepts an array of routes and checks if the route the user is trying to visit matches one of the routes passed to it.
- *
- * The `createRouteMatcher` helper function returns a function that accepts a Vue Router route location and will return `true` if the user is trying to access a route that matches on of the routes passed to `createRouteMatcher`.
- *
- * @example
- * ['/foo', '/bar(.*)']
- * @example
- * [/^\/foo\/.*$/]
- *
- * @deprecated This function will be removed in the next major version. Use Nuxt's built-in
- * route middleware to protect pages instead: create a named middleware that checks the user's
- * authentication status and opt pages into it with `definePageMeta()`. Child routes inherit
- * the middleware applied to their parent, so a single declaration can protect a whole section.
- *
- * ```ts
- * // app/middleware/auth.ts
- * export default defineNuxtRouteMiddleware(() => {
- *   const { isSignedIn } = useAuth();
- *
- *   if (!isSignedIn.value) {
- *     return navigateTo('/sign-in');
- *   }
- * });
- * ```
- */
-export const createRouteMatcher = (routes: RouteMatcherParam) => {
-  deprecated(
-    'createRouteMatcher',
-    "Use Nuxt's built-in route middleware to protect pages instead: create a named middleware that checks the user's authentication status and opt pages into it with `definePageMeta({ middleware: 'auth' })`.",
-  );
-
-  const matcher = createPathMatcher(routes);
-  return (to: RouteLocation) => matcher(to.path);
-};
diff --git a/packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts b/packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts
index 2c0432bca07..99fa714d0a1 100644
--- a/packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts
+++ b/packages/nuxt/src/runtime/server/__tests__/clerkMiddleware.test.ts
@@ -1,8 +1,8 @@
-import { createApp, createError, eventHandler, setResponseHeader, toWebHandler } from 'h3';
+import { normalizePath } from '@clerk/shared/pathMatcher';
+import { createApp, createError, eventHandler, getRequestURL, setResponseHeader, toWebHandler } from 'h3';
 import { describe, expect, test, vi } from 'vitest';
 
 import { clerkMiddleware } from '../clerkMiddleware';
-import { createRouteMatcher } from '../routeMatcher';
 
 const SESSION_AUTH_RESPONSE = {
   userId: 'user_2jZSstSbxtTndD9P7q4kDl0VVZa',
@@ -66,13 +66,12 @@ vi.mock('../clerkClient', () => {
 });
 
 describe('clerkMiddleware(params)', () => {
-  test('returns 400 when createRouteMatcher encounters malformed percent-encoding', async () => {
-    const isProtectedRoute = createRouteMatcher(['/api/admin(.*)']);
+  test('returns 400 when the handler encounters malformed percent-encoding while matching paths', async () => {
     const app = createApp();
     const handler = toWebHandler(app);
     app.use(
       clerkMiddleware(event => {
-        if (isProtectedRoute(event)) {
+        if (normalizePath(getRequestURL(event).pathname).startsWith('/api/admin')) {
           throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
         }
       }),
diff --git a/packages/nuxt/src/runtime/server/__tests__/routeMatcher.test.ts b/packages/nuxt/src/runtime/server/__tests__/routeMatcher.test.ts
deleted file mode 100644
index 20bb76ff391..00000000000
--- a/packages/nuxt/src/runtime/server/__tests__/routeMatcher.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { getRequestURL } from 'h3';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { createRouteMatcher } from '../routeMatcher';
-
-const { mockDeprecated } = vi.hoisted(() => ({
-  mockDeprecated: vi.fn(),
-}));
-
-vi.mock('@clerk/shared/deprecated', () => ({
-  deprecated: mockDeprecated,
-}));
-
-vi.mock('#imports', () => ({
-  getRequestURL,
-}));
-
-describe('createRouteMatcher', () => {
-  beforeEach(() => {
-    mockDeprecated.mockClear();
-  });
-
-  it('should emit a deprecation warning when called', () => {
-    createRouteMatcher(['/api/admin(.*)']);
-
-    expect(mockDeprecated).toHaveBeenCalledWith(
-      'createRouteMatcher',
-      "Match API route paths natively inside `clerkMiddleware()` instead, for example: `getRequestURL(event).pathname.startsWith('/api/admin')`. To protect pages, use Nuxt's built-in route middleware.",
-    );
-  });
-});
diff --git a/packages/nuxt/src/runtime/server/index.ts b/packages/nuxt/src/runtime/server/index.ts
index 6ce2112d43c..2b623e85036 100644
--- a/packages/nuxt/src/runtime/server/index.ts
+++ b/packages/nuxt/src/runtime/server/index.ts
@@ -1,5 +1,4 @@
 export * from '@clerk/backend';
 export { clerkClient } from './clerkClient';
 export { clerkMiddleware } from './clerkMiddleware';
-export { createRouteMatcher } from './routeMatcher';
 export type { AuthFn } from './types';
diff --git a/packages/nuxt/src/runtime/server/routeMatcher.ts b/packages/nuxt/src/runtime/server/routeMatcher.ts
deleted file mode 100644
index 7509cf09e13..00000000000
--- a/packages/nuxt/src/runtime/server/routeMatcher.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { deprecated } from '@clerk/shared/deprecated';
-import type { PathMatcherParam } from '@clerk/shared/pathMatcher';
-import { createPathMatcher } from '@clerk/shared/pathMatcher';
-import type { H3Event } from 'h3';
-
-import { getRequestURL } from '#imports';
-
-export type RouteMatcherParam = PathMatcherParam;
-
-/**
- * `createRouteMatcher` is a Clerk helper function that allows you to protect multiple routes. It accepts an array of routes and checks if the route the user is trying to visit matches one of the routes passed to it.
- *
- * The `createRouteMatcher` helper function returns a function that accepts a Vue Router route location and will return `true` if the user is trying to access a route that matches on of the routes passed to `createRouteMatcher`.
- *
- * @example
- * ['/foo', '/bar(.*)']
- * @example
- * [/^\/foo\/.*$/]
- *
- * @deprecated This function will be removed in the next major version. Match API route paths natively
- * inside `clerkMiddleware()` instead, and protect pages with Nuxt's built-in route middleware:
- *
- * ```ts
- * import { clerkMiddleware } from '@clerk/nuxt/server';
- *
- * export default clerkMiddleware(event => {
- *   const { isAuthenticated } = event.context.auth();
- *   const { pathname } = getRequestURL(event);
- *
- *   if (!isAuthenticated && pathname.startsWith('/api/admin')) {
- *     throw createError({ statusCode: 401, statusMessage: 'Unauthorized' });
- *   }
- * });
- * ```
- */
-export const createRouteMatcher = (routes: RouteMatcherParam) => {
-  deprecated(
-    'createRouteMatcher',
-    "Match API route paths natively inside `clerkMiddleware()` instead, for example: `getRequestURL(event).pathname.startsWith('/api/admin')`. To protect pages, use Nuxt's built-in route middleware.",
-  );
-
-  const matcher = createPathMatcher(routes);
-  return (event: H3Event) => {
-    const url = getRequestURL(event);
-    return matcher(new URL(url).pathname);
-  };
-};

From 6140eccbff332a52b01590aa4c44ca0d5b5b5509 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 27 Jul 2026 12:01:03 -0700
Subject: [PATCH 2/4] chore(nuxt): Set minimum compatible Nuxt version to 4

---
 packages/nuxt/src/module.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/nuxt/src/module.ts b/packages/nuxt/src/module.ts
index 07eca1118ab..be25674982e 100644
--- a/packages/nuxt/src/module.ts
+++ b/packages/nuxt/src/module.ts
@@ -41,7 +41,7 @@ export default defineNuxtModule<ModuleOptions>({
     version: PACKAGE_VERSION,
     configKey: 'clerk',
     compatibility: {
-      nuxt: '>=3.0.0',
+      nuxt: '>=4.0.0',
     },
   },
   setup(options, nuxt) {

From 93c5b996c991db64b63155c9993e615c46617a50 Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Mon, 27 Jul 2026 13:36:21 -0700
Subject: [PATCH 3/4] chore: add changeset

---
 .changeset/major-nuxt-drop-nuxt-3.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/major-nuxt-drop-nuxt-3.md

diff --git a/.changeset/major-nuxt-drop-nuxt-3.md b/.changeset/major-nuxt-drop-nuxt-3.md
new file mode 100644
index 00000000000..f0c847dd9c0
--- /dev/null
+++ b/.changeset/major-nuxt-drop-nuxt-3.md
@@ -0,0 +1,5 @@
+---
+'@clerk/nuxt': major
+---
+
+Drop support for Nuxt 3, which reaches end-of-life on July 31, 2026. `@clerk/nuxt` now requires Nuxt 4. If you are still on Nuxt 3, follow the [Nuxt upgrade guide](https://nuxt.com/docs/getting-started/upgrade) to upgrade your project before updating `@clerk/nuxt`.

From 5b2f2d1db2c11779bac3983583d6e1bc3da2a9fb Mon Sep 17 00:00:00 2001
From: wobsoriano <sorianorobertc@gmail.com>
Date: Tue, 28 Jul 2026 10:04:14 -0700
Subject: [PATCH 4/4] chore(nuxt): Align Node engines with Nuxt 4 and caveat
 plain pathname checks

---
 .changeset/major-nuxt-drop-nuxt-3.md          | 2 +-
 .changeset/major-nuxt-remove-route-matcher.md | 5 ++++-
 packages/nuxt/package.json                    | 2 +-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.changeset/major-nuxt-drop-nuxt-3.md b/.changeset/major-nuxt-drop-nuxt-3.md
index f0c847dd9c0..98c036bec33 100644
--- a/.changeset/major-nuxt-drop-nuxt-3.md
+++ b/.changeset/major-nuxt-drop-nuxt-3.md
@@ -2,4 +2,4 @@
 '@clerk/nuxt': major
 ---
 
-Drop support for Nuxt 3, which reaches end-of-life on July 31, 2026. `@clerk/nuxt` now requires Nuxt 4. If you are still on Nuxt 3, follow the [Nuxt upgrade guide](https://nuxt.com/docs/getting-started/upgrade) to upgrade your project before updating `@clerk/nuxt`.
+Drop support for Nuxt 3, which reaches end-of-life on July 31, 2026. `@clerk/nuxt` now requires Nuxt 4, and the minimum supported Node.js version is now `^20.19.0 || >=22.12.0` to match Nuxt 4's own requirement. If you are still on Nuxt 3, follow the [Nuxt upgrade guide](https://nuxt.com/docs/getting-started/upgrade) to upgrade your project before updating `@clerk/nuxt`.
diff --git a/.changeset/major-nuxt-remove-route-matcher.md b/.changeset/major-nuxt-remove-route-matcher.md
index 5579947104e..abcf03453ca 100644
--- a/.changeset/major-nuxt-remove-route-matcher.md
+++ b/.changeset/major-nuxt-remove-route-matcher.md
@@ -59,7 +59,10 @@ Migrate my Nuxt project away from Clerk's removed `createRouteMatcher` API.
 4. Remove the `createRouteMatcher` imports and calls. Keep `clerkMiddleware()`
    itself. Middleware logic unrelated to auth protection (headers, locale
    redirects, etc.) may stay, using plain `getRequestURL(event).pathname`
-   checks.
+   checks. Plain pathname checks do not normalize percent-encoding
+   (`/api/%61dmin` will not match a check for `/api/admin`), so never use
+   them for auth or security decisions. Those belong on the resource itself,
+   as in steps 2 and 3.
 5. Make sure every route previously covered by a matcher pattern (including
    glob patterns like `/dashboard(.*)`) now has its own check, then verify the
    project builds.
diff --git a/packages/nuxt/package.json b/packages/nuxt/package.json
index abbb4cbcdce..8025ff624cb 100644
--- a/packages/nuxt/package.json
+++ b/packages/nuxt/package.json
@@ -83,7 +83,7 @@
     "vue": "catalog:repo"
   },
   "engines": {
-    "node": ">=20.9.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "publishConfig": {
     "access": "public"