E-commerce

Initialiser le projet Next.js

Un projet Next.js qui démarre en local, avec Tailwind et shadcn/ui prêts à l'emploi.

Prérequis : Node.js installé. Terminal ouvert dans le dossier du projet.

1. Installe pnpm si besoin

   npm install -g pnpm

   pnpm est le gestionnaire de paquets choisi pour ce projet — plus rapide et plus économe en espace disque que npm.
   👁 Comment voir le résultat : tape pnpm -v. Un numéro de version s'affiche (ex. 9.12.0) — sinon l'installation a échoué.
2. Crée le projet Next.js

   pnpm create next-app@latest . --typescript --tailwind --eslint --app --src-dir=false --import-alias "@/*"

   Le nom du dossier ne doit pas contenir de majuscules (contrainte npm). S'il en contient, crée le projet dans un dossier temporaire au nom valide puis déplace tout son contenu dans ton dossier de travail.
   👁 Comment voir le résultat : tape ls. Tu dois voir apparaître app/, package.json, tailwind.config.ts — la commande a rempli ton dossier de fichiers.
3. Initialise shadcn/ui

   pnpm dlx shadcn@latest init

   Ça crée components.json et lib/utils.ts, et prépare Tailwind pour recevoir des composants shadcn/ui prêts à copier.
   👁 Comment voir le résultat : tape ls components.json lib/utils.ts — les deux fichiers doivent exister, sans message d'erreur « No such file ».
4. Crée l'arborescence du projet

   mkdir -p lib/auth lib/db lib/validations prisma tests

   On sépare dès le départ : authentification, accès base de données, schémas de validation. Ça évite le fichier fourre-tout de 2000 lignes plus tard.
   👁 Comment voir le résultat : tape ls lib — les dossiers auth, db, validations doivent apparaître.
5. Initialise Git et fais le premier commit

   git init
   git add -A
   git commit -m "chore: init projet Next.js"

   👁 Comment voir le résultat : tape git log --oneline — une ligne avec ton message de commit doit s'afficher.
6. Lance le serveur et vérifie

   pnpm dev

   Ouvre http://localhost:3000. Si tu as une erreur 500 mentionnant un module introuvable (ex. Can't resolve 'xxx') alors qu'il est bien dans package.json : supprime node_modules, pnpm-lock.yaml et .next, relance pnpm install puis pnpm dev. C'est presque toujours une installation incomplète, pas un bug de code.
   👁 Comment voir le résultat : dans ton navigateur, ouvre localhost:3000. Tu dois voir la page d'accueil par défaut de Next.js. Le terminal affiche Ready et n'affiche pas d'erreur rouge.

Base de données — Prisma + Supabase

Une base PostgreSQL en ligne, avec les tables Produit, Commande et LigneCommande créées via Prisma.

Prérequis : étape 1 validée.

1. Crée un projet sur Supabase
   Va sur supabase.com → New project. Choisis un nom, une région proche, et un mot de passe de base de données — note-le quelque part.
   👁 Comment voir le résultat : le tableau de bord Supabase affiche ton projet avec un statut « Active » (après ~1-2 minutes).
2. Récupère l'URL de connexion
   Dans le projet Supabase : Project Settings → Database → Connection string, mode URI. Copie l'URL complète (mot de passe inclus).
3. Installe Prisma

   pnpm add prisma --save-dev
   pnpm add @prisma/client
   pnpm dlx prisma init

   Crée prisma/schema.prisma et un fichier .env avec une variable DATABASE_URL vide.
   👁 Comment voir le résultat : tape ls prisma/schema.prisma — le fichier doit exister.
4. Colle l'URL dans .env

   # .env
   DATABASE_URL="postgresql://postgres:[MOT-DE-PASSE]@[HOST]:5432/postgres"

   Ce fichier ne doit jamais être commit (déjà dans .gitignore par défaut) — il contient un mot de passe.
5. Écris le schéma
   Dans prisma/schema.prisma, sous les blocs generator/datasource déjà présents, ajoute :

   model Produit {
     id        String   @id @default(cuid())
     nom       String
     prix      Int      // en centimes, pour éviter les erreurs d'arrondi
     stock     Int      @default(0)
     createdAt DateTime @default(now())
   }
   
   model Commande {
     id        String   @id @default(cuid())
     clientId  String
     statut    String   @default("EN_ATTENTE")
     total     Int
     createdAt DateTime @default(now())
     lignes    LigneCommande[]
   }
   
   model LigneCommande {
     id           String   @id @default(cuid())
     commandeId   String
     commande     Commande @relation(fields: [commandeId], references: [id])
     produitId    String
     quantite     Int
     prixUnitaire Int
   }

   Les prix sont stockés en centimes (entiers) plutôt qu'en euros décimaux — évite les erreurs d'arrondi classiques avec les nombres flottants.
6. Applique la migration et vérifie

   pnpm dlx prisma migrate dev --name init
   pnpm dlx prisma studio

   migrate dev crée les tables et génère le client Prisma typé. studio ouvre une interface web locale pour voir/éditer les données à la main.
   👁 Comment voir le résultat : prisma studio ouvre localhost:5555 — les tables Produit, Commande et LigneCommande doivent apparaître dans la liste de gauche.

Piège fréquent : connexion refusée → vérifie qu'aucun caractère spécial du mot de passe (@, #...) n'est mal encodé dans l'URL. Supabase propose un bouton pour copier l'URL déjà encodée.

Authentification — Better Auth

Des comptes clients — historique de commandes, adresse — et une zone /dashboard protégée pour l'admin.

Prérequis : étape 2 validée (schéma Prisma en place).

1. Installe Better Auth

   pnpm add better-auth

   👁 Comment voir le résultat : better-auth apparaît dans package.json.
2. Crée la config serveur

   // lib/auth/auth.ts
   import { betterAuth } from "better-auth";
   import { prismaAdapter } from "better-auth/adapters/prisma";
   import { prisma } from "@/lib/db/client";
   
   export const auth = betterAuth({
     database: prismaAdapter(prisma, { provider: "postgresql" }),
     emailAndPassword: { enabled: true },
   });

   Crée aussi lib/db/client.ts qui exporte une instance unique de PrismaClient — évite d'en recréer une à chaque appel.
3. Ajoute les tables auth au schéma

   pnpm dlx @better-auth/cli generate
   pnpm dlx prisma migrate dev --name add_auth

   Better Auth génère automatiquement les modèles User, Session, Account dans schema.prisma.
   👁 Comment voir le résultat : ouvre prisma studio — les tables User, Session, Account doivent apparaître.
4. Ajoute le secret dans .env

   # .env
   BETTER_AUTH_SECRET="génère une chaîne aléatoire longue"
   BETTER_AUTH_URL="http://localhost:3000"

5. Crée la route API

   // app/api/auth/[...all]/route.ts
   import { auth } from "@/lib/auth/auth";
   import { toNextJsHandler } from "better-auth/next-js";
   
   export const { GET, POST } = toNextJsHandler(auth);

   👁 Comment voir le résultat : relance pnpm dev et ouvre un endpoint Better Auth (ex. localhost:3000/api/auth/ok) — tu dois obtenir une réponse JSON, pas une erreur 404.
6. Crée le client auth et les pages
   Un fichier lib/auth/client.ts avec createAuthClient(), puis des pages /signup et /login qui appellent authClient.signUp.email(...) et authClient.signIn.email(...).
   👁 Comment voir le résultat : crée un compte test sur localhost:3000/signup, puis vérifie dans Prisma Studio qu'une ligne apparaît dans la table User.
7. Protège /dashboard
   Un middleware.ts à la racine qui vérifie la session sur les routes /dashboard/* et redirige vers /login si absente.
   👁 Comment voir le résultat : en navigation privée (non connecté), va sur localhost:3000/dashboard — tu dois être redirigé vers /login.

Piège fréquent : si la doc officielle de Better Auth diffère de ce qui est écrit ici, suis la doc — c'est une librairie qui évolue vite. Dis-le moi si un nom de fonction a changé, on ajuste.

Paiement — Stripe

Encaisser un vrai paiement carte, en toute sécurité.

Prérequis : étape 3 validée.

1. Crée un compte Stripe (mode test)
   Sur stripe.com — le mode test permet de simuler des paiements sans vraie carte bancaire, avec le numéro 4242 4242 4242 4242.
2. Installe le SDK

   pnpm add stripe

   👁 Comment voir le résultat : stripe apparaît dans package.json.
3. Ajoute les clés dans .env

   # .env
   STRIPE_SECRET_KEY="sk_test_..."
   STRIPE_WEBHOOK_SECRET="whsec_..."

   Les deux se trouvent dans le tableau de bord Stripe, section Développeurs.
4. Crée une session de paiement

   // lib/stripe/checkout.ts
   "use server";
   import Stripe from "stripe";
   const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
   
   export async function createCheckoutSession(items) {
     const session = await stripe.checkout.sessions.create({
       mode: "payment",
       line_items: items.map((i) => ({
         price_data: {
           currency: "eur",
           product_data: { name: i.nom },
           unit_amount: i.prix,
         },
         quantity: i.quantite,
       })),
       success_url: `${process.env.BETTER_AUTH_URL}/commande/succes`,
       cancel_url: `${process.env.BETTER_AUTH_URL}/panier`,
     });
     return session.url;
   }

   👁 Comment voir le résultat : se testera concrètement une fois la page panier branchée à l'étape 5 — pour l'instant, vérifie juste que le fichier ne contient pas d'erreur TypeScript dans ton éditeur.
5. Crée la route webhook

   // app/api/stripe/webhook/route.ts
   // Vérifie la signature avec STRIPE_WEBHOOK_SECRET,
   // puis à l'événement "checkout.session.completed",
   // passe la Commande correspondante en statut PAYEE.

   Ne marque jamais une commande payée depuis le navigateur (côté client) — seul le webhook, signé par Stripe, fait foi. Sinon n'importe qui peut appeler ton API et se déclarer « payé » sans payer.
   👁 Comment voir le résultat : lance stripe listen --forward-to localhost:3000/api/stripe/webhook dans un terminal séparé — il doit afficher Ready! Your webhook signing secret is whsec_.... Fais un paiement test (carte 4242 4242 4242 4242) : ce terminal doit logguer l'événement checkout.session.completed.

Piège fréquent : en local, Stripe ne peut pas atteindre localhost pour envoyer le webhook — utilise stripe listen --forward-to localhost:3000/api/stripe/webhook (CLI Stripe) pendant le développement.

Catalogue, panier & commandes

Parcourir les produits, les mettre au panier, passer commande.

Prérequis : étape 4 validée.

1. Page catalogue
   app/produits/page.tsx — liste les produits via prisma.produit.findMany(), une carte par produit (shadcn/ui Card).
   👁 Comment voir le résultat : ouvre localhost:3000/produits — les produits que tu as ajoutés dans Prisma Studio doivent s'afficher, un par carte.
2. Panier côté client

   pnpm add zustand

   Le panier vit dans le navigateur avant le paiement — pas besoin de base de données pour ça. Zustand garde l'état du panier accessible depuis n'importe quel composant, sans tout faire remonter via les props.
3. Page panier
   app/panier/page.tsx — récapitule les articles ajoutés, calcule le total, bouton « Payer » qui appelle createCheckoutSession.
   👁 Comment voir le résultat : depuis le catalogue, ajoute 2-3 produits au panier puis ouvre localhost:3000/panier — ils doivent y être listés avec le bon total (calcule-le à la main pour vérifier).
4. Crée la commande avant le paiement
   Crée la Commande en base avec statut EN_ATTENTE juste avant de rediriger vers Stripe — le webhook n'aura plus qu'à la faire passer à PAYEE.
   👁 Comment voir le résultat : clique sur « Payer » depuis le panier — juste avant la redirection vers Stripe, une nouvelle ligne EN_ATTENTE doit apparaître dans la table Commande (Prisma Studio).

Tests — Vitest & Playwright

Automatiser la vérification du parcours critique.

Prérequis : étapes 4 et 5 validées.

1. Installe et configure Vitest

   pnpm add -D vitest

   Écris un test dans tests/panier.validation.test.ts qui vérifie que calculTotalPanier calcule correctement le total du panier avec plusieurs articles.
2. Installe et configure Playwright

   pnpm create playwright

   Répond aux questions de l'installateur (TypeScript, dossier tests-e2e). Écris un test qui : crée un compte → ajoute un produit au panier → paie avec une carte de test Stripe → vérifie que la commande apparaît en base.
3. Lance les tests

   pnpm exec vitest run
   pnpm exec playwright test

   👁 Comment voir le résultat : le terminal affiche un résumé avec un nombre de tests « passed » en vert. Playwright peut aussi ouvrir un rapport HTML (pnpm exec playwright show-report) qui montre le parcours étape par étape, avec captures d'écran si un test échoue.

Déploiement — Vercel

Une URL publique et fonctionnelle.

Prérequis : étape 6 validée.

1. Ajoute la génération Prisma au build

   // package.json
   "scripts": { "postinstall": "prisma generate" }

   Sans ça, le build Vercel plante — le client Prisma doit être régénéré après chaque install en production.
2. Pousse le code sur GitHub

   git remote add origin URL-DE-TON-DEPOT
   git push -u origin master

   👁 Comment voir le résultat : rafraîchis la page du dépôt sur GitHub — tes fichiers doivent y apparaître.
3. Importe le projet sur Vercel
   Sur vercel.com → Add New → Project → sélectionne le dépôt GitHub.
   👁 Comment voir le résultat : le tableau de bord Vercel passe de « Building » à « Ready », avec un lien de prévisualisation cliquable.
4. Renseigne les variables d'environnement
   Copie DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL (URL Vercel finale), STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET dans Settings → Environment Variables.
   👁 Comment voir le résultat : pas d'effet visible immédiatement — redéploie (« Redeploy ») puis teste à l'étape suivante.
5. Configure le webhook Stripe en production
   Dans le tableau de bord Stripe : ajoute un endpoint pointant vers https://tondomaine.vercel.app/api/stripe/webhook — l'URL locale utilisée avec la CLI ne fonctionne plus une fois déployé.
   👁 Comment voir le résultat : dans le tableau de bord Stripe, section Webhooks, l'endpoint doit afficher un statut vert « Enabled ».
6. Déploie et vérifie en ligne
   Ouvre l'URL fournie par Vercel, refais le parcours critique à la main : créer un compte → ajouter un produit au panier → payer avec une carte de test → vérifier la commande.
   👁 Comment voir le résultat : sur l'URL *.vercel.app, un paiement test complet doit faire passer la commande en PAYEE — vérifiable dans Prisma Studio ou directement dans Supabase.