Ajouter Clerk

Version : Vérifiez package.json pour la version du SDK — consultez la skill clerk pour la table des versions. Les différences Core 2 sont signalées avec des encadrés > **Core 2 ONLY (skip if current SDK):**.

Cette skill configure Clerk pour l'authentification en suivant la documentation officielle de démarrage rapide.

Référence rapide

Si le projet dispose de components.json (shadcn/ui), appliquez le thème shadcn après la configuration. Consultez la skill clerk-custom-ui → Thème shadcn.

Détection du framework

Vérifiez package.json pour identifier le framework :

Pour les autres plateformes :

• Chrome Extension : https://clerk.com/docs/chrome-extension/getting-started/quickstart
• Android : https://clerk.com/docs/android/getting-started/quickstart
• iOS : https://clerk.com/docs/ios/getting-started/quickstart
• Vanilla JavaScript : https://clerk.com/docs/js-frontend/getting-started/quickstart

Arbre de décision

Demande utilisateur : "Ajouter Clerk" / "Ajouter l'authentification"
    │
    ├─ Lire package.json
    │
    ├─ Authentification existante détectée ?
    │   ├─ OUI → Audit → Plan de migration
    │   └─ NON → Installation nouvelle
    │
    ├─ Identifier le framework → WebFetch le guide de démarrage → Suivre les instructions
    │   └─ Next.js ? → Créer proxy.ts (Next.js <=15 : middleware.ts)
    │
    └─ components.json existe ? → OUI → Appliquer le thème shadcn (voir clerk-custom-ui)

Processus de configuration

1. Détecter le framework

Lisez le fichier package.json du projet et associez les dépendances au tableau ci-dessus.

2. Récupérer le guide de démarrage rapide

Utilisez WebFetch pour récupérer le guide de démarrage rapide officiel du framework détecté :

WebFetch: https://clerk.com/docs/{framework}/getting-started/quickstart
Prompt: "Extract the complete setup instructions including all code snippets, file paths, and configuration steps."

3. Suivre les instructions

Exécutez chaque étape du guide de démarrage rapide :

• Installer les packages requis
• Configurer les variables d'environnement
• Ajouter le provider et le proxy/middleware
• Créer les routes de connexion/inscription si nécessaire
• Tester l'intégration

Next.js : Créez proxy.ts (Next.js <=15 : middleware.ts). Consultez la skill clerk-nextjs-patterns pour les stratégies de middleware.

shadcn/ui détecté (components.json existe) : TOUJOURS appliquez le thème shadcn. Consultez la skill clerk-custom-ui → section Thème shadcn.

4. Obtenir les clés API

Deux façons d'obtenir les clés API de développement :

Sans clé (Automatique)

• Lors de l'initialisation du SDK, Clerk génère automatiquement les clés de développement et affiche une fenêtre contextuelle « Claim your application »
• Aucune configuration manuelle de clé requise — les clés sont créées et injectées automatiquement
• Chemin le plus simple pour les nouveaux projets

Manuel (Tableau de bord)

• Obtenez les clés depuis dashboard.clerk.com si Sans clé ne se déclenche pas
• Clé publique : Commence par pk_test_ ou pk_live_
• Clé secrète : Commence par sk_test_ ou sk_live_
• Définissez en tant que variables d'environnement : NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY et CLERK_SECRET_KEY

Migration depuis un autre fournisseur d'authentification

Si le projet dispose déjà d'une authentification, créez un plan de migration avant de la remplacer.

Détecter l'authentification existante

Vérifiez package.json pour les bibliothèques d'authentification existantes :

• next-auth / @auth/core → NextAuth/Auth.js
• @supabase/supabase-js → Supabase Auth
• firebase / firebase-admin → Firebase Auth
• @aws-amplify/auth → AWS Cognito
• auth0 / @auth0/nextjs-auth0 → Auth0
• passport → Passport.js
• Implémentation JWT/session personnalisée

Processus de migration

1. Audit de l'authentification actuelle - Identifiez tous les points d'authentification :

   • Pages de connexion/inscription
   • Gestion des sessions/tokens
   • Routes et middleware protégés
   • Stockage des données utilisateur (tables de base de données, IDs externes)
   • Fournisseurs OAuth configurés

2. Créez un plan de migration - Considérez :

   • Exportation de données utilisateur - Exportez les utilisateurs et importez via l'API Backend de Clerk
   • Hachages de mots de passe - Clerk peut mettre à niveau les hachages en Bcrypt de façon transparente
   • IDs externes - Stockez les IDs utilisateur hérités comme external_id dans Clerk
   • Gestion des sessions - Les sessions existantes se termineront lors du passage

3. Choisissez la stratégie de migration :

   • Big bang - Basculer tous les utilisateurs en même temps (plus simple, nécessite une fenêtre de maintenance)
   • Migration progressive - Exécuter les deux systèmes temporairement (risque plus faible, complexité plus élevée)

Référence de migration

• Aperçu de la migration : https://clerk.com/docs/guides/development/migrating/overview

Notes sur le SDK

Noms des packages

Core 2 ONLY (skip if current SDK) : Les packages React et Expo ont des noms différents : @clerk/clerk-react et @clerk/clerk-expo (avec le préfixe clerk-).

Placement de ClerkProvider (Next.js)

ClerkProvider doit être placé à l'intérieur de <body>, et non envelopper <html> :

// root layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ClerkProvider>{children}</ClerkProvider>
      </body>
    </html>
  )
}

Core 2 ONLY (skip if current SDK) : ClerkProvider peut envelopper <html> directement.

Rendu dynamique (Next.js)

Pour le rendu dynamique avec les données d'authentification, utilisez la prop dynamic :

<ClerkProvider dynamic>{children}</ClerkProvider>

Exigence Node.js

Nécessite Node.js 20.9.0 ou supérieur.

Core 2 ONLY (skip if current SDK) : Minimum Node.js 18.17.0.

Package de thèmes

Les thèmes sont installés depuis @clerk/ui :

npm install @clerk/ui

Core 2 ONLY (skip if current SDK) : Les thèmes proviennent de @clerk/themes au lieu de @clerk/ui.

Thème shadcn

Si le projet utilise shadcn/ui (vérifiez la présence de components.json à la racine du projet), appliquez le thème shadcn pour que les composants Clerk correspondent au système de design de l'application :

npm install @clerk/ui

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

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

Importez également le CSS shadcn dans vos styles globaux :

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

Core 2 ONLY (skip if current SDK) : Importez depuis @clerk/themes et @clerk/themes/shadcn.css à la place.

Pièges courants

Voir aussi

• clerk-custom-ui - Composants de connexion/inscription personnalisés
• clerk-nextjs-patterns - Modèles Next.js avancés
• clerk-react-patterns - Modèles React SPA
• clerk-react-router-patterns - Modèles React Router
• clerk-vue-patterns - Modèles Vue
• clerk-nuxt-patterns - Modèles Nuxt
• clerk-astro-patterns - Modèles Astro
• clerk-tanstack-patterns - Modèles TanStack Start
• clerk-expo-patterns - Modèles Expo
• clerk-chrome-extension-patterns - Modèles Chrome Extension
• clerk-orgs - Organisations multi-locataires B2B
• clerk-webhooks - Synchronisation webhook → base de données
• clerk-testing - Configuration de test E2E
• clerk-swift - Authentification iOS native
• clerk-android - Authentification Android native
• clerk-backend-api - Explorateur API REST Backend

Documentation

• Aperçu du démarrage rapide : https://clerk.com/docs/getting-started/quickstart/overview
• Guide de migration : https://clerk.com/docs/guides/development/migrating/overview
• Documentation complète : https://clerk.com/docs