---
id: gh-clerk-nuxt-patterns
name: "clerk-nuxt-patterns"
url: https://skills.yangsir.net/skill/gh-clerk-nuxt-patterns
author: clerk
domain: ai-app-building-integration
tags: ["nuxt", "clerk", "authentication", "frontend-development", "web-development"]
install_count: 13800
rating: 4.50 (120 reviews)
github: https://github.com/clerk/skills/tree/main/skills/frameworks/clerk-nuxt-patterns
---

# clerk-nuxt-patterns

> 此技能提供将 Clerk 认证集成到 Nuxt 3 应用的最佳实践和模式。它涵盖了使用中间件进行路由保护、在 Nitro 服务器 API 路由中处理认证，以及利用 `useAuth`/`useUser` 组合式函数实现客户端响应式体验。通过提供 SSR 安全的认证策略，它简化了安全且高性能 Nuxt 应用的开发，减少了常见陷阱并加速了上市时间。

**Stats**: 13,800 installs · 4.5/5 (120 reviews)

## Before / After 对比

### Nuxt 3 认证集成效率

**Before**:

在 Nuxt 3 应用中手动实现认证功能，特别是要兼顾 SSR 安全性和客户端状态管理时，过程复杂且容易出错，耗时较长。

**After**:

采用 Clerk Nuxt 认证模式，通过预置的中间件、组合式函数和服务器路由处理，显著简化了认证集成，确保了安全性和开发效率。

| Metric | Before | After | Change |
|---|---|---|---|
| 认证功能开发时间 | 60分钟 | 10分钟 | -83% |

## Readme

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


---
*Source: https://skills.yangsir.net/skill/gh-clerk-nuxt-patterns*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-clerk-nuxt-patterns/markdown*