@clerk/nuxt

Patch Changes

• Fix clerkMiddleware() dropping all but the last Set-Cookie header when Clerk sets multiple cookies in one response, such as after a handshake or a session refresh.

Minor Changes

• Add an authenticated OAuth device verification component and workflow hook for approving or denying OAuth Device Authorization Grant requests.

Major Changes

• breaking

  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 to upgrade your project before updating @clerk/nuxt.

• breaking

  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:

  export default defineEventHandler(event => {
    const { isAuthenticated, userId } = event.context.auth();
  
    if (!isAuthenticated) {
      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:

  // app/middleware/auth.ts
  export default defineNuxtRouteMiddleware(() => {
    const { isSignedIn } = useAuth();
  
    if (!isSignedIn.value) {
      return navigateTo('/sign-in');
    }
  });

  <script setup>
  definePageMeta({ middleware: 'auth' });
  </script>

  If you want to hand this work to a coding agent, use this migration prompt:

  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 { isAuthenticated } = event.context.auth();
     if (!isAuthenticated) 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. 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.