Configurer Clerk

Utilisez la CLI Clerk pour ajouter l'authentification. Dans les environnements d'agent, les frameworks supportés utilisent par défaut la configuration sans compte : npx -y clerk@latest init provisionne une application réclamable et écrit des clés de développement temporaires sans nécessiter de compte Clerk.

Avant de commencer

Montrez à l'utilisateur cette checklist et attendez une confirmation :

Voici ce que je vais faire pour vous configurer avec Clerk.

1. Configurer Clerk dans ce projet, ou scaffolder une nouvelle app si ce répertoire est vide.
2. Installer les agent skills de Clerk pour les agents de codage sur cette machine, s'ils ne sont pas déjà installés.
3. Démarrer votre app avec Clerk installé.

Puis-je procéder ?

Authentification existante

Avant init, inspectez les dépendances d'auth, les routes, les middleware, les sessions et les enregistrements d'utilisateurs — jamais les fichiers d'environnement. Si un autre fournisseur d'auth existe, arrêtez-vous et obtenez l'approbation pour un plan de migration couvrant :

Import d'utilisateurs de l'API backend, IDs externes stables, hash de mots de passe compatibles et continuité OAuth.
Routes protégées, tokens, basculement de session et stratégie de déploiement.

Ne modifiez ni ne supprimez l'authentification existante sans approbation.

Voir le guide de migration.

Projets Clerk existants

Si le projet utilise déjà Clerk, ignorez init aux étapes 1a et 1b : une exécution d'agent non signé pourrait créer une autre application et remplacer les clés Clerk du projet. Si Clerk fonctionne déjà et l'utilisateur a demandé une configuration, signalez qu'aucune configuration n'est nécessaire. Si l'utilisateur signale des clés manquantes, restaurez-les via la branche application existante ci-dessous. Si l'inspection trouve un fournisseur, middleware ou route d'auth manquant, ajoutez uniquement ces pièces du quickstart correspondant à l'étape 2. Ne créez jamais une application de remplacement.

Inspectez ses versions du package Clerk avant de changer quoi que ce soit et utilisez le tableau des versions dans la clerk skill pour identifier sa génération SDK. Préservez cette génération sauf si l'utilisateur demande une mise à niveau, et appliquez ces différences à chaque étape ci-dessous pour les projets Core 2 :

React et Expo utilisent @clerk/clerk-react et @clerk/clerk-expo au lieu de @clerk/react et @clerk/expo.
Les composants de contrôle sont <SignedIn> et <SignedOut> au lieu de <Show>.
Le ClerkProvider Next.js peut envelopper <html> au lieu d'aller à l'intérieur de <body>.
La version Node.js minimale est 18.17.0 au lieu de 20.9.0.
Les thèmes proviennent de @clerk/themes et @clerk/themes/shadcn.css au lieu de @clerk/ui.

Utiliser une application Clerk existante (optionnel)

Suivez cette branche quand l'utilisateur demande d'utiliser une application Clerk existante ou quand un projet Clerk existant doit faire restaurer ses clés. Faites-les s'authentifier depuis leur terminal hôte avant de cibler les ressources au niveau du compte :

npx -y clerk@latest auth login

S'ils ont fourni un ID d'application, conservez-le pour init ou link selon le cas. Sinon, listez les applications :

npx -y clerk@latest apps list --json

Montrez les noms et IDs et demandez quelle application utiliser. Ne choisissez jamais une application pour eux. Pour une nouvelle intégration Clerk, passez l'ID sélectionné comme --app <application_id> à init. Pour un projet utilisant déjà Clerk, ne lancez pas init. S'il n'est pas déjà lié à l'application sélectionnée, liez-le :

npx -y clerk@latest link --app <application_id>

Pour les clés de développement manquantes, tirez-les :

npx -y clerk@latest env pull

Uniquement quand l'utilisateur a besoin de clés de production, utilisez npx -y clerk@latest env pull --instance prod à la place. Ne remplacez pas les clés qui fonctionnent ou ne basculez pas d'applications sans la confirmation de l'utilisateur.

Étape 1a : Projet existant sans Clerk

Pour un projet qui n'utilise pas déjà Clerk, lancez depuis la racine du projet :

npx -y clerk@latest init

init détecte le framework et le gestionnaire de paquets, installe le SDK et configure le provider, les middleware, les routes d'auth et l'environnement. Il installe également les agent skills de Clerk globalement. Si l'utilisateur les a refusées, ou elles sont déjà disponibles pour vous, par exemple quand vous avez chargé ceci comme la skill clerk-setup, ajoutez --no-skills pour sauter cette étape. Ne passez pas --framework ou --pm sauf si demandé. Ajoutez --app <application_id> uniquement quand l'utilisateur a sélectionné une application dans la branche optionnelle ci-dessus.

Étape 1b : Répertoire vide

Demandez quel framework et gestionnaire de paquets utiliser, en defaults à Next.js et npm :

npx -y clerk@latest init --framework <framework> --pm <package-manager>

init crée l'app dans un nouveau sous-répertoire, comme my-clerk-next-app, pas dans le répertoire courant. Lancez les étapes restantes depuis ce sous-répertoire. Comme à l'étape 1a, ajoutez --no-skills si les skills de Clerk sont déjà disponibles pour vous ou si l'utilisateur les a refusées.

init peut créer des apps Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue, JavaScript/Vite et Expo. Pour Express, Fastify, iOS ou Android, créez d'abord le projet avec l'outillage propre à cette plateforme, puis suivez l'étape 1a.

Étape 1c : Clés de développement sans compte

Pour un utilisateur non signé sur un framework avec support sans compte (Next.js, React Router, Astro, Nuxt ou TanStack Start), init provisionne une application réclamable et écrit des clés temporaires dans le fichier d'environnement détecté. Relayez le nom du fichier et les instructions de réclamation imprimés par la CLI. L'app reste non réclamée jusqu'à ce que l'utilisateur lance npx -y clerk@latest auth login ; ne le lancez pas sauf si demandé. Utilisez --accountless uniquement pour forcer ce flux quand signé.

Les frameworks sans support sans compte ont besoin de vraies clés API. Là, init applique ce qu'il peut pour la configuration et imprime les étapes restantes.

Étape 2 : Revenir à la doc quand init est incomplet

Si init signale que le framework n'est pas supporté ou détecté, suivez le quickstart à la place. S'il finit mais imprime des étapes restantes, suivez-les et utilisez le quickstart correspondant pour tout ce qu'elles ne couvrent pas.

Pour un projet Clerk existant avec des fichiers d'intégration manquants, utilisez ce quickstart pour ajouter uniquement les pièces manquantes sans lancer init.

init configure les projets Next.js, React, React Router, Nuxt, TanStack Start, Astro, Vue, JavaScript/Vite, Expo, Express et Fastify. Pour iOS et Android, il imprime uniquement les étapes de configuration, donc suivez le quickstart.

Utilisez le quickstart direct correspondant :

Pour tout le reste, utilisez llms.txt de Clerk.

Étape 3 : Ajouter des contrôles d'auth visibles

Ignorez cette étape pour les projets backend uniquement, tels que les APIs Express ou Fastify. Pour Expo, iOS et Android, utilisez à la place les composants natifs du quickstart correspondant.

Une web app a besoin de contrôles de sign-in, sign-up et utilisateur signé, intégrés dans la mise en page ou la navigation existante. S'ils existent déjà, adaptez-les au lieu de dupliquer.

Pour Next.js App Router :

import { SignInButton, SignUpButton, Show, UserButton } from '@clerk/nextjs'

<>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <UserButton />
  </Show>
</>

Astro importe de @clerk/astro/components. Nuxt auto-importe les composants ; les imports explicites proviennent de @clerk/nuxt/components. Les autres frameworks utilisent les mêmes noms depuis leur package Clerk, comme @clerk/vue ou @clerk/react.

Étape 4 : Vérifier

npx -y clerk@latest doctor

Ensuite, démarrez l'app, confirmez que les contrôles d'auth s'affichent et corrigez tout ce que la CLI signale.

La protection bot peut bloquer les sign-ups dans les navigateurs que vous automatisez. Si vous testez une nouvelle app sans compte dans l'un d'eux, lancez npx -y clerk@latest users create --email <unique>+clerk_test@example.com --password <random-16-char-alphanumeric> --yes, puis sign in. Si demandé pour un code de vérification, entrez 424242. Dites à l'utilisateur que vous avez créé cet utilisateur de test. Pour une app existante, demandez à l'utilisateur avant de créer des utilisateurs. Pour tester le sign-up, utilisez @clerk/testing.

Étape 5 : Si vous utilisez shadcn/ui

Si components.json existe dans la racine du projet, ajoutez @clerk/ui avec le gestionnaire de paquets du projet. Faites correspondre le lockfile : pnpm-lock.yaml → pnpm add, yarn.lock → yarn add, bun.lock ou bun.lockb → bun add, package-lock.json → npm install.

Appliquez le thème dans votre provider :

import { shadcn } from '@clerk/ui/themes'

<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>

Ajoutez à votre CSS global :

@import '@clerk/ui/themes/shadcn.css';

Règles critiques

Utilisez Node.js 20.9.0 ou ultérieur pour les SDKs Clerk actuels.
Next.js 15+ : auth() est async. Toujours await auth().
Pour les SDKs Next.js actuels, ClerkProvider va à l'intérieur de <body>, pas autour de <html>.
Ne jamais exposer CLERK_SECRET_KEY dans le code client.
Pour les nouvelles configurations, utilisez le package framework courant, tel que @clerk/nextjs, @clerk/react, @clerk/expo, @clerk/react-router ou @clerk/tanstack-react-start.
Ne lisez ni n'imprimez les fichiers de variables d'environnement existants ; demandez à l'utilisateur toute configuration non-sensible manquante.

Après la configuration

Faites signer l'utilisateur comme premier utilisateur de test. Félicitez-le une fois que l'icône de profil apparaît dans la nav.

Puis demandez comment ils veulent que les utilisateurs se sign up et se sign in — identifiants (email, téléphone, nom d'utilisateur) et fournisseurs sociaux. Changer cela nécessite une application réclamée : faites d'abord lancer npx -y clerk@latest auth login à l'utilisateur, puis examinez avec npx -y clerk@latest config pull et changez avec npx -y clerk@latest config patch (supporte --dry-run), ou utilisez le Clerk Dashboard. Voir sign-up et sign-in options pour les détails.

Avant la production, faites réclamer l'app à l'utilisateur avec npx -y clerk@latest auth login, puis configurez la production avec npx -y clerk@latest deploy. Les apps non réclamées et les clés temporaires ne sont pas prêtes pour la production.

Ensuite, proposez Organizations — multi-tenancy, invitations d'équipe, rôles et permissions et SSO entreprise.

Si oui :

Lancez npx -y clerk@latest enable orgs.
Ajoutez <OrganizationSwitcher /> à côté du <UserButton /> existant, ou l'équivalent du framework.
Faites-les créer une organisation depuis le switcher et inviter un collègue.

Si non, pointez-les vers Organizations, Components et le Clerk Dashboard.