clerk-nuxt-patterns

★ 54

by clerk · part of clerk/skills

Nuxt 3 auth patterns with @clerk/nuxt - middleware, composables, server

🔥🔥🔥🔥✓ VerifiedFreeQuick setup

🧩 One of 7 skills in the clerk/skills package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

name: clerk-nuxt-patterns description: 'Nuxt 3 auth patterns with @clerk/nuxt - middleware, composables, server API routes, SSR. Triggers on: Nuxt auth, useAuth composable, clerkMiddleware Nuxt, server API Clerk, Nuxt route protection.' license: MIT allowed-tools: WebFetch metadata: author: clerk version: 1.0.0

Nuxt Patterns

What Do You Need?

Task	Reference
Protect routes with middleware	references/nuxt-middleware.md
Auth in server API routes (Nitro)	references/server-api-routes.md
useAuth / useUser in components	references/composables.md
SSR-safe auth patterns	references/ssr-auth.md

References

Reference	Description
`references/nuxt-middleware.md`	Route protection, clerkMiddleware()
`references/server-api-routes.md`	Nitro server route auth
`references/composables.md`	useAuth, useUser, useClerk
`references/ssr-auth.md`	SSR hydration, server vs client

Mental Model

@clerk/nuxt auto-imports all Clerk components and composables — no explicit imports needed in <script setup>.

Composables (useAuth, useUser) — client-side reactive, inside <script setup>
Server routes (clerkClient) — Nitro server routes, event.context.auth
Middleware (clerkMiddleware) — auto-registered, use auth().protect() to lock routes

Minimal Pattern

<!-- pages/dashboard.vue -->
<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
const { userId } = useAuth()
</script>

<template>
  <Show when="signed-in">
    <p>Hello {{ userId }}</p>
  </Show>
</template>

definePageMeta({ middleware: 'auth' }) uses the built-in auth middleware from @clerk/nuxt.

Common Pitfalls

Symptom	Cause	Fix
Composables return `undefined` on server	useAuth is client-only	Use `event.context.auth` in server routes
Route not protected	Missing `middleware: 'auth'` meta	Add `definePageMeta({ middleware: 'auth' })`
`clerkClient` not available	Wrong import path	Import from `@clerk/nuxt/server`
Hydration mismatch	Rendering auth state before mounted	Wrap in `<ClientOnly>` or check `isLoaded`
Env vars not picked up	Wrong prefix	Nuxt requires `NUXT_PUBLIC_` for public, `NUXT_` for server

Org-Aware Pattern

<script setup lang="ts">
const { orgId, orgRole } = useAuth()
</script>

<template>
  <div v-if="orgId">
    <p>Org: {{ orgId }}</p>
    <p v-if="orgRole === 'org:admin'">Admin panel</p>
  </div>
  <div v-else>
    <OrganizationSwitcher />
  </div>
</template>

Docs

Nuxt SDK

Copy & paste — that's it

npx skills add https://github.com/clerk/skills --skill clerk-nuxt-patterns

Run this in your project — your agent picks the skill up automatically.

Setup

npm install @clerk/nuxt

.env:

NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
NUXT_CLERK_SECRET_KEY=sk_...

nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@clerk/nuxt'],
})

This single line auto-configures middleware, plugins, and component auto-imports.