---
name: clerk-nuxt-patterns
description: 'Nuxt 3 auth patterns with @clerk/nuxt - middleware, composables, server'
license: MIT
allowed-tools: WebFetch
metadata:
  author: clerk
  version: 1.0.0
title: clerk-nuxt-patterns
canonical_url: https://skilld.dev/gh/clerk/skills/clerk-nuxt-patterns
last_updated: 2026-09-11T06:23:37.000Z
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [evals/evals.json](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/evals/evals.json), [references/composables.md](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/references/composables.md), [references/nuxt-middleware.md](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/references/nuxt-middleware.md), [references/server-api-routes.md](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/references/server-api-routes.md), [references/ssr-auth.md](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/references/ssr-auth.md), [templates/nuxt-basic-auth/app.vue](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/templates/nuxt-basic-auth/app.vue), [templates/nuxt-basic-auth/nuxt.config.ts](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/templates/nuxt-basic-auth/nuxt.config.ts), [templates/nuxt-basic-auth/package.json](https://skilld.dev/api/skills-raw/clerk/skills/clerk-nuxt-patterns/templates/nuxt-basic-auth/package.json).
>
> If the user asked to install this Skill, run `npx skilld@beta install skilld:clerk/skills/clerk-nuxt-patterns`. Install writes the Skill files into the project, so every session loads them.

# 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 |

## Setup

```
npm install @clerk/nuxt
```

`.env`:
```
NUXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
NUXT_CLERK_SECRET_KEY=sk_...
```

`nuxt.config.ts`:
```typescript
export default defineNuxtConfig({
  modules: ['@clerk/nuxt'],
})
```

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

## 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

```vue
<!-- 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

```vue
<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>
```

## See Also

- `clerk-setup` - Initial Clerk install
- `clerk-custom-ui` - Custom flows & appearance
- `clerk-orgs` - B2B organizations

## Docs

[Nuxt SDK](https://clerk.com/docs/nuxt/getting-started/quickstart)