Créer une Auth Skill

Guide pour ajouter l'authentification à des applications TypeScript/JavaScript en utilisant Better Auth.

Pour les exemples de code et la syntaxe, consultez better-auth.com/docs.

Phase 1 : Planification (OBLIGATOIRE avant l'implémentation)

Avant d'écrire du code, collectez les exigences en analysant le projet et en posant à l'utilisateur des questions structurées. Cela garantit que l'implémentation répond à ses besoins.

Étape 1 : Analyser le projet

Analysez la base de code pour détecter automatiquement :

• Framework — Cherchez next.config, svelte.config, nuxt.config, astro.config, vite.config, ou les fichiers d'entrée Express/Hono.
• Base de données/ORM — Cherchez prisma/schema.prisma, drizzle.config, les dépendances package.json (pg, mysql2, better-sqlite3, mongoose, mongodb).
• Auth existante — Cherchez les bibliothèques auth existantes (next-auth, lucia, clerk, supabase/auth, firebase/auth) dans package.json ou les imports.
• Gestionnaire de paquets — Vérifiez pnpm-lock.yaml, yarn.lock, bun.lockb, ou package-lock.json.

Utilisez ce que vous trouvez pour pré-remplir les valeurs par défaut et ignorer les questions auxquelles vous pouvez déjà répondre avec confiance.

Étape 2 : Poser les questions de planification

Utilisez l'outil AskQuestion pour poser à l'utilisateur toutes les questions applicables en un seul appel. Ignorez toute question pour laquelle vous avez déjà une réponse confiante à partir de l'analyse. Groupez-les sous un titre comme « Planification de la configuration Auth ».

Questions à poser :

1. Type de projet (ignorer si détecté)

   • Invite : « Quel type de projet est-ce ? »
   • Options : Nouveau projet à partir de zéro | Ajouter auth à un projet existant | Migration depuis une autre bibliothèque auth

2. Framework (ignorer si détecté)

   • Invite : « Quel framework utilisez-vous ? »
   • Options : Next.js (App Router) | Next.js (Pages Router) | SvelteKit | Nuxt | Astro | Express | Hono | SolidStart | Autre

3. Base de données et ORM (ignorer si détecté)

   • Invite : « Quelle configuration de base de données utiliserez-vous ? »
   • Options : PostgreSQL (Prisma) | PostgreSQL (Drizzle) | PostgreSQL (driver pg) | MySQL (Prisma) | MySQL (Drizzle) | MySQL (driver mysql2) | SQLite (Prisma) | SQLite (Drizzle) | SQLite (driver better-sqlite3) | MongoDB (Mongoose) | MongoDB (driver natif)

4. Méthodes d'authentification (toujours poser, autoriser plusieurs)

   • Invite : « Quelles méthodes de connexion avez-vous besoin ? »
   • Options : Email et mot de passe | OAuth social (Google, GitHub, etc.) | Magic link (email sans mot de passe) | Passkey (WebAuthn) | Numéro de téléphone
   • allow_multiple: true

5. Fournisseurs sociaux (uniquement s'ils ont sélectionné OAuth social ci-dessus — poser dans un appel ultérieur)

   • Invite : « Quels fournisseurs sociaux avez-vous besoin ? »
   • Options : Google | GitHub | Apple | Microsoft | Discord | Twitter/X
   • allow_multiple: true

6. Vérification email (uniquement si Email et mot de passe a été sélectionné ci-dessus — poser dans un appel ultérieur)

   • Invite : « Voulez-vous exiger la vérification de l'email ? »
   • Options : Oui | Non

7. Fournisseur email (uniquement si la vérification email est Oui, ou si la réinitialisation du mot de passe est sélectionnée dans les fonctionnalités — poser dans un appel ultérieur)

   • Invite : « Comment voulez-vous envoyer les emails ? »
   • Options : Resend | Le simuler pour l'instant (console.log)

8. Fonctionnalités et plugins (toujours poser, autoriser plusieurs)

   • Invite : « Quelles fonctionnalités supplémentaires avez-vous besoin ? »
   • Options : Authentification à deux facteurs (2FA) | Organisations / équipes | Tableau de bord administrateur | Jetons porteurs API | Réinitialisation du mot de passe | Aucune de ces options
   • allow_multiple: true

9. Pages auth (toujours poser, autoriser plusieurs — pré-sélectionner en fonction des réponses antérieures)

   • Invite : « Quelles pages auth avez-vous besoin ? »
   • Les options varient en fonction des réponses antérieures :
     • Toujours disponibles : Connexion | Inscription
     • Si Email et mot de passe sélectionnés : Mot de passe oublié | Réinitialiser le mot de passe
     • Si vérification email activée : Vérification email
   • allow_multiple: true

10. Style de l'interface auth (toujours poser)

    • Invite : « Quel style voulez-vous pour les pages auth ? Choisissez-en un ou décrivez le vôtre. »
    • Options : Minimaliste et propre | Carte centrée avec arrière-plan | Disposition divisée (formulaire + image héros) | Flottant / glassmorphisme | Autre (je vais décrire)

Étape 3 : Résumer le plan

Après avoir collecté les réponses, présentez un plan d'implémentation concis sous forme de liste de contrôle markdown. Exemple :

## Plan d'implémentation Auth

- **Framework :** Next.js (App Router)
- **Base de données :** PostgreSQL via Prisma
- **Méthodes auth :** Email/mot de passe, OAuth Google, OAuth GitHub
- **Plugins :** 2FA, Organisations, Vérification email
- **Interface :** Formulaires personnalisés

### Étapes
1. Installer `better-auth` et `@better-auth/cli`
2. Créer `lib/auth.ts` avec la configuration serveur
3. Créer `lib/auth-client.ts` avec le client React
4. Configurer le gestionnaire de route à `app/api/auth/[...all]/route.ts`
5. Configurer l'adaptateur Prisma et générer le schéma
6. Ajouter les fournisseurs OAuth Google et GitHub
7. Activer les plugins `twoFactor` et `organization`
8. Configurer le gestionnaire de vérification email
9. Exécuter les migrations
10. Créer les pages de connexion / inscription

Demandez à l'utilisateur de confirmer le plan avant de passer à la Phase 2.

Phase 2 : Implémentation

Procédez ici uniquement après que l'utilisateur a confirmé le plan de la Phase 1.

Suivez l'arbre de décision ci-dessous, guidé par les réponses collectées ci-dessus.

Est-ce un nouveau projet/projet vide ?
├─ OUI → Configuration d'un nouveau projet
│   1. Installer better-auth (+ paquets scoped selon le plan)
│   2. Créer auth.ts avec toute la configuration prévue
│   3. Créer auth-client.ts avec le client framework
│   4. Configurer le gestionnaire de route
│   5. Configurer les variables d'environnement
│   6. Exécuter la migration/génération CLI
│   7. Ajouter les plugins du plan
│   8. Créer les pages d'interface auth
│
├─ MIGRATION → Migration depuis l'auth existante
│   1. Auditer l'auth actuelle pour les lacunes
│   2. Planifier la migration progressive
│   3. Installer better-auth aux côtés de l'auth existante
│   4. Migrer les routes, puis la logique de session, puis l'interface
│   5. Supprimer l'ancienne bibliothèque auth
│   6. Voir les guides de migration dans la documentation
│
└─ AJOUT → Ajouter auth à un projet existant
    1. Analyser la structure du projet
    2. Installer better-auth
    3. Créer la configuration auth correspondant au plan
    4. Ajouter le gestionnaire de route
    5. Exécuter les migrations de schéma
    6. Intégrer aux pages existantes
    7. Ajouter les plugins et fonctionnalités prévus

À la fin de l'implémentation, guidez les utilisateurs en détail sur les prochaines étapes (par exemple, configurer les identifiants d'application OAuth, déployer les variables d'environnement, tester les flux).

Installation

Cœur : npm install better-auth

Paquets scoped (selon les besoins) : | Paquet | Cas d'usage | |--------|-----------| | @better-auth/passkey | Auth WebAuthn/Passkey | | @better-auth/sso | SSO entreprise SAML/OIDC | | @better-auth/stripe | Paiements Stripe | | @better-auth/scim | Provisionnement utilisateur SCIM | | @better-auth/expo | React Native/Expo |

Variables d'environnement

BETTER_AUTH_SECRET=<32+ caractères, générer avec : openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<votre chaîne de connexion à la base de données>

Ajoutez les secrets OAuth selon les besoins : GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID, etc.

Configuration serveur (auth.ts)

Emplacement : lib/auth.ts ou src/lib/auth.ts

Configuration minimale nécessaire :

• database - Connexion ou adaptateur
• emailAndPassword: { enabled: true } - Pour l'auth email/mot de passe

Configuration standard ajoute :

• socialProviders - Fournisseurs OAuth (google, github, etc.)
• emailVerification.sendVerificationEmail - Gestionnaire de vérification email
• emailAndPassword.sendResetPassword - Gestionnaire de réinitialisation de mot de passe

Configuration complète ajoute :

• plugins - Tableau de plugins de fonctionnalités
• session - Paramètres d'expiration et de cache de cookies
• account.accountLinking - Liaison multi-fournisseur
• rateLimit - Configuration du limiteur de débit

Types d'export : export type Session = typeof auth.$Infer.Session

Configuration client (auth-client.ts)

Importer par framework : | Framework | Import | |-----------|--------| | React/Next.js | better-auth/react | | Vue | better-auth/vue | | Svelte | better-auth/svelte | | Solid | better-auth/solid | | JavaScript vanilla | better-auth/client |

Les plugins client vont dans createAuthClient({ plugins: [...] }).

Exports courants : signIn, signUp, signOut, useSession, getSession

Configuration du gestionnaire de route

Composants serveur Next.js : Ajouter le plugin nextCookies() à la configuration auth.

Migrations de base de données

Réexécutez après l'ajout de plugins.

Adaptateurs de base de données

Plugins courants

Modèle de plugin : Plugin serveur + plugin client + exécuter les migrations.

Implémentation de l'interface Auth

Flux de connexion :

1. signIn.email({ email, password }) ou signIn.social({ provider, callbackURL })
2. Gérer error dans la réponse
3. Rediriger en cas de succès

Vérification de session (client) : Le hook useSession() retourne { data: session, isPending }

Vérification de session (serveur) : auth.api.getSession({ headers: await headers() })

Routes protégées : Vérifier la session, rediriger vers /sign-in si null.

Liste de contrôle de sécurité

• [ ] BETTER_AUTH_SECRET défini (32+ caractères)
• [ ] advanced.useSecureCookies: true en production
• [ ] trustedOrigins configuré
• [ ] Limiteurs de débit activés
• [ ] Vérification email activée
• [ ] Réinitialisation du mot de passe implémentée
• [ ] 2FA pour les applications sensibles
• [ ] Protection CSRF NON désactivée
• [ ] account.accountLinking examiné

Dépannage

Ressources

• Documentation
• Exemples
• Plugins
• CLI
• Guides de migration