Agent Skills
› midudev/autoskills
› clerk-nuxt-patterns
clerk-nuxt-patterns
GitHub提供Nuxt 3集成Clerk的认证模式，涵盖中间件、组合式API、服务端API及SSR安全实践。指导用户配置环境变量、自动导入composables、保护路由及处理客户端与服务端状态差异，解决常见坑点。
Trigger Scenarios
Nuxt auth
useAuth composable
clerkMiddleware Nuxt
server API Clerk
Nuxt route protection
Install
npx skills add midudev/autoskills --skill clerk-nuxt-patterns -g -y
SKILL.md
Frontmatter
{
"name": "clerk-nuxt-patterns",
"license": "MIT",
"metadata": {
"author": "clerk",
"version": "1.0.0"
},
"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.",
"allowed-tools": "WebFetch"
}
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:
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, useauth().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>
See Also
clerk-setup- Initial Clerk installclerk-custom-ui- Custom flows & appearanceclerk-orgs- B2B organizations
Docs
Version History
- 0ec7253 Current 2026-07-24 20:52
