AutoGineer
Generated banner for Clerk Nuxt Patterns
Generated logo for Clerk Nuxt Patterns

Clerk Nuxt Patterns

ClerkOfficialCreated by clerk

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
  • Has scripts
Download ZIP

From the author

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.
— the description by clerk

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive set of patterns for integrating Clerk authentication into Nuxt 3 projects. It covers the essential building blocks including route protection via middleware, handling authentication state in components with composables, securing server-side API routes, and managing SSR-safe authentication flows. It serves as a reference for developers to implement secure, user-aware features in their Nuxt applications.

What it does

  • Configures Clerk authentication within the Nuxt 3 framework.
  • Provides patterns for protecting client-side routes using built-in middleware.
  • Demonstrates how to access authentication state and user data via auto-imported composables.
  • Explains how to secure Nitro server API routes using server-side context.
  • Offers guidance on handling SSR hydration and common authentication pitfalls.
  • Shows how to implement organization-aware authentication flows.

When to use it

  • When starting a new Nuxt 3 project that requires user authentication.
  • When migrating existing Nuxt applications to use Clerk for identity management.
  • When you need to protect specific routes or API endpoints based on user session status.
  • When building B2B applications requiring organization-based access control.

Advantages

  • Simplifies integration with auto-imported components and composables.
  • Provides standardized patterns for both client-side and server-side authentication.
  • Reduces boilerplate code for common tasks like route protection and user data retrieval.
  • Addresses specific Nuxt-related challenges like SSR hydration and environment variable configuration.

Usage examples

“How do I protect a dashboard page in my Nuxt 3 app using Clerk?”
The agent will explain how to add definePageMeta({ middleware: 'auth' }) to the page script to automatically redirect unauthenticated users.
“How can I access the current user's ID in a Nuxt component?”
The agent will show how to use the useAuth() composable to retrieve the userId and display it in the template.
“How do I secure a Nitro server route in Nuxt with Clerk?”
The agent will provide an example of using event.context.auth within a server route to verify the user's session.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/clerk/clerk-nuxt-patterns/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip clerk-nuxt-patterns.zip -d .agents/skills

Documentation by clerk

Nuxt Patterns

What Do You Need?

TaskReference
Protect routes with middlewarereferences/nuxt-middleware.md
Auth in server API routes (Nitro)references/server-api-routes.md
useAuth / useUser in componentsreferences/composables.md
SSR-safe auth patternsreferences/ssr-auth.md

References

ReferenceDescription
references/nuxt-middleware.mdRoute protection, clerkMiddleware()
references/server-api-routes.mdNitro server route auth
references/composables.mduseAuth, useUser, useClerk
references/ssr-auth.mdSSR 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, 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

SymptomCauseFix
Composables return undefined on serveruseAuth is client-onlyUse event.context.auth in server routes
Route not protectedMissing middleware: 'auth' metaAdd definePageMeta({ middleware: 'auth' })
clerkClient not availableWrong import pathImport from @clerk/nuxt/server
Hydration mismatchRendering auth state before mountedWrap in <ClientOnly> or check isLoaded
Env vars not picked upWrong prefixNuxt 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 install

  • clerk-custom-ui - Custom flows & appearance

  • clerk-orgs - B2B organizations

Docs

Nuxt SDK

Files

references/nuxt-middleware.md

Nuxt Middleware (CRITICAL)

Built-in Auth Middleware

@clerk/nuxt auto-registers an auth named middleware. Use it with definePageMeta:

<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
</script>

This redirects unauthenticated users to the sign-in page automatically.

Custom Route Middleware

Create middleware/require-org.ts for custom logic:

export default defineNuxtRouteMiddleware(() => {
  const { isSignedIn, orgId } = useAuth()

  if (!isSignedIn.value) {
    return navigateTo('/sign-in')
  }

  if (!orgId.value) {
    return navigateTo('/select-org')
  }
})

Apply to a page:

<script setup lang="ts">
definePageMeta({ middleware: ['auth', 'require-org'] })
</script>

Server-Side Middleware (Nitro)

For API-level protection in server/middleware/auth.ts:

import { clerkClient } from '@clerk/nuxt/server'

export default defineEventHandler(async (event) => {
  const auth = event.context.auth

  if (getRequestURL(event).pathname.startsWith('/api/protected')) {
    if (!auth?.userId) {
      throw createError({ statusCode: 401, message: 'Unauthorized' })
    }
  }
})

Redirect URLs

Configure in .env:

NUXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NUXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NUXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/dashboard
NUXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/dashboard

Docs

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Needs Node.js

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
clerk
Publisher
Clerk (Official)
Source
clerk/skills · skills/clerk-nuxt-patterns · commit c5d2c0d
Licence
MIT License (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by clerk.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download clerk-nuxt-patterns.zip