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

See Also

• clerk-setup

• Initial Clerk install

• clerk-custom-ui

• Custom flows & appearance

• clerk-orgs

• B2B organizations

Docs

Nuxt SDK