Motifs Nuxt

De quoi avez-vous besoin ?

Tâche	Référence
Protéger les routes avec middleware	references/nuxt-middleware.md
Auth dans les routes API serveur (Nitro)	references/server-api-routes.md
useAuth / useUser dans les composants	references/composables.md
Motifs d'auth SSR-safe	references/ssr-auth.md

Références

Référence	Description
`references/nuxt-middleware.md`	Protection des routes, clerkMiddleware()
`references/server-api-routes.md`	Auth des routes serveur Nitro
`references/composables.md`	useAuth, useUser, useClerk
`references/ssr-auth.md`	Hydration SSR, serveur vs client

Installation

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'],
})

Cette seule ligne configure automatiquement le middleware, les plugins et les auto-imports de composants.

Modèle mental

@clerk/nuxt auto-importe tous les composants et composables Clerk — aucun import explicite nécessaire dans <script setup>.

Composables (useAuth, useUser) — client-side réactifs, à l'intérieur de <script setup>
Routes serveur (clerkClient) — routes serveur Nitro, event.context.auth
Middleware (clerkMiddleware) — auto-enregistré, utilisez auth().protect() pour verrouiller les routes

Motif minimal

<!-- pages/dashboard.vue -->
<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
const { userId } = useAuth()
</script>

<template>
  <Show when="signed-in">
    <p>Bonjour {{ userId }}</p>
  </Show>
</template>

definePageMeta({ middleware: 'auth' }) utilise le middleware auth intégré de @clerk/nuxt.

Pièges courants

Symptôme	Cause	Solution
Les composables retournent `undefined` sur le serveur	useAuth est client-only	Utilisez `event.context.auth` dans les routes serveur
Route non protégée	Middleware 'auth' manquant dans les meta	Ajoutez `definePageMeta({ middleware: 'auth' })`
`clerkClient` non disponible	Mauvais chemin d'import	Importez depuis `@clerk/nuxt/server`
Désalignement d'hydration	État d'auth rendu avant le montage	Enveloppez dans `<ClientOnly>` ou vérifiez `isLoaded`
Variables d'environnement non détectées	Mauvais préfixe	Nuxt requiert `NUXT_PUBLIC_` pour public, `NUXT_` pour serveur

Motif Org-Aware

<script setup lang="ts">
const { orgId, orgRole } = useAuth()
</script>

<template>
  <div v-if="orgId">
    <p>Org : {{ orgId }}</p>
    <p v-if="orgRole === 'org:admin'">Panneau admin</p>
  </div>
  <div v-else>
    <OrganizationSwitcher />
  </div>
</template>

Voir aussi

clerk-setup - Installation initiale de Clerk
clerk-custom-ui - Flux personnalisés et apparence
clerk-orgs - Organisations B2B

Documentation

Nuxt SDK

clerk-nuxt-patterns