FileAttente

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 deux tables (Queue, Entry) 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 Queue {
     id        String   @id @default(cuid())
     name      String
     ownerId   String
     createdAt DateTime @default(now())
     entries   Entry[]
   }
   
   model Entry {
     id        String   @id @default(cuid())
     queueId   String
     queue     Queue    @relation(fields: [queueId], references: [id])
     name      String
     note      String?
     status    String   @default("WAITING")
     createdAt DateTime @default(now())
   }

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 Queue et Entry 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

S'inscrire, se connecter, et protéger /dashboard des visiteurs non connectés.

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.

CRUD Files d'attente

Créer, lister et supprimer une file depuis /dashboard.

Prérequis : étape 3 validée (session utilisateur disponible).

1. Ajoute des composants shadcn/ui

   pnpm dlx shadcn@latest add button input card

   👁 Comment voir le résultat : ls components/ui — button.tsx, input.tsx, card.tsx doivent apparaître.
2. Écris les Server Actions

   // app/dashboard/actions.ts
   "use server";
   // createQueue(formData): valide le nom avec Zod,
   // récupère la session, crée la Queue avec ownerId = session.user.id
   // deleteQueue(id): vérifie que ownerId === session.user.id avant de supprimer

   La vérification ownerId === session.user.id côté serveur est obligatoire — sans elle, n'importe quel utilisateur connecté pourrait supprimer les files d'un autre.
3. Valide les entrées avec Zod

   // lib/validations/queue.ts
   import { z } from "zod";
   export const createQueueSchema = z.object({
     name: z.string().min(1).max(80),
   });

4. Construis la page /dashboard
   Liste les files du propriétaire connecté via prisma.queue.findMany({ where: { ownerId } }), un formulaire pour en créer une nouvelle, un bouton supprimer par ligne.
   👁 Comment voir le résultat : connecté sur localhost:3000/dashboard, crée une file test via le formulaire — elle doit apparaître immédiatement dans la liste, et une nouvelle ligne doit exister dans Prisma Studio (table Queue).

CRUD Entrées

Ajouter une personne à une file, la marquer servie ou la retirer.

Prérequis : étape 4 validée.

1. Crée la page de détail

   // app/dashboard/queues/[id]/page.tsx

   Récupère la Queue et ses entries via prisma.queue.findUnique({ where: { id }, include: { entries: true } }) — vérifie que queue.ownerId === session.user.id, sinon renvoie une 404.
   👁 Comment voir le résultat : clique sur une de tes files depuis /dashboard — tu dois arriver sur une page dédiée avec son nom affiché, sans erreur.
2. Écris les actions
   addEntry(queueId, formData) — crée une Entry avec status: "WAITING". markServed(id) et removeEntry(id) — vérifient que la file appartient bien à l'utilisateur avant d'agir.
3. Affiche la liste des entrées
   Trie par createdAt croissant (premier arrivé, premier affiché). Un badge de couleur selon le status.
   👁 Comment voir le résultat : ajoute 2-3 entrées test via le formulaire — elles doivent apparaître dans l'ordre d'ajout, avec un badge « en attente ». Clique sur « marquer servi » : le badge doit changer sans recharger la page.

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/queue.validation.test.ts qui vérifie que createQueueSchema rejette un nom vide et accepte un nom valide.
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 → se connecte → crée une file → ajoute une entrée → la marque servie.
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 ouvrir un rapport HTML (pnpm exec playwright show-report) qui rejoue 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 (mets l'URL Vercel finale) dans Settings → Environment Variables.
   👁 Comment voir le résultat : pas d'effet visible immédiatement — redéploie (« Redeploy ») puis teste à l'étape suivante.
5. Déploie et vérifie en ligne
   Ouvre l'URL fournie par Vercel, refais le parcours critique à la main : inscription → créer une file → ajouter une entrée → marquer servie.
   👁 Comment voir le résultat : sur l'URL *.vercel.app, le parcours complet doit fonctionner exactement comme en local — création de compte, file, entrée, tout doit persister en base (vérifiable dans Supabase).