●Change8

Migrating to Clerk @clerk/nuxt@3.0.0

Version @clerk/nuxt@3.0.0 introduces 2 breaking changes. This guide details how to update your code.

Released: 7/29/2026

2
Breaking Changes
5
Migration Steps
10
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

`@clerk/nuxt``@clerk/nuxt/server``createRouteMatcher``defineEventHandler``event.context.auth()``createError``defineNuxtRouteMiddleware``useAuth``navigateTo``definePageMeta`

Breaking Changes

●Issue #1

Support for Nuxt 3 has been dropped. The `@clerk/nuxt` package now requires Nuxt 4. The minimum supported Node.js version is now `^20.19.0 || >=22.12.0`.

●Issue #2

The `createRouteMatcher` function has been removed from `@clerk/nuxt/server` and is no longer auto-imported on the client-side. Auth checks should now be implemented directly within API route event handlers or via named route middleware for pages.

Migration Steps

  1. 1
    If you are using Nuxt 3, upgrade your project to Nuxt 4 by following the [Nuxt upgrade guide](https://nuxt.com/docs/getting-started/upgrade) before updating `@clerk/nuxt`.
  2. 2
    For API routes previously protected by `createRouteMatcher`, move the authentication check into the event handler itself. Example: `const { isAuthenticated } = event.context.auth(); if (!isAuthenticated) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); }`
  3. 3
    For pages previously protected by `createRouteMatcher`, create a named route middleware in `app/middleware/` that checks `useAuth()` and redirects if necessary using `navigateTo()`. Then, opt pages into this middleware using `definePageMeta({ middleware: 'auth' })`. Child routes will inherit middleware from their parent.
  4. 4
    Remove imports and calls to `createRouteMatcher`. Keep `clerkMiddleware()` if it contains logic unrelated to auth protection.
  5. 5
    Ensure all routes previously covered by `createRouteMatcher` patterns (including glob patterns) now have explicit auth checks implemented directly on the resource or via route middleware.

Release Summary

This release drops support for Nuxt 3, requiring Nuxt 4 and updating the minimum Node.js version. It also removes `createRouteMatcher` from `@clerk/nuxt/server` and client-side auto-import, shifting auth checks to be handled directly within API route event handlers or via named route middleware for pages.

Need More Details?

View the full release notes and all changes for Clerk @clerk/nuxt@3.0.0.

View Full Changelog