Version : 1.1 — Mars 2026 Scope : Tout projet SaaS / web app Gentle Designs Objectif : Fournir la stack technique de référence pour chaque couche d'un projet, avec outil retenu + alternative + justification, afin d'empêcher Claude Code de dériver vers ses choix par défaut
Principes de sélection
Chaque outil retenu répond à trois critères : il fonctionne nativement avec Next.js et TypeScript sans friction d'intégration, il a un free tier suffisant pour valider un MVP en production réelle, et il n'introduit pas de dette technique qui force une migration ultérieure. L'alternative listée n'est pas un "plan B par défaut" — c'est un choix légitime quand le contexte du projet l'exige. L'argument "pourquoi pas X" est là pour empêcher Claude Code de dériver vers ses choix par défaut.
Couche Développement
| Besoin | Outil retenu | Alternative | Pourquoi ce choix / Pourquoi pas l'alternative |
|---|---|---|---|
| Coding agent | Claude Code | — | Pas d'alternative. C'est le moteur de tout le workflow Gentle Designs. |
| IDE | VS Code + Claude Code intégré | Claude Code terminal standalone | L'intégration VS Code donne la vue fichiers + le terminal Claude côte à côte. Le standalone convient pour les tâches ponctuelles. |
| Version control | GitHub | GitLab | GitHub a le connecteur Claude Desktop natif, les GitHub Actions, et l'intégration Vercel en 1 clic. GitLab est plus complet pour le CI/CD entreprise mais surdimensionné pour un solo dev. |
Couche Langages
| Langage | Rôle | Scope |
|---|---|---|
| TypeScript | Langage principal de tous les projets web. Non négociable — le typage est ce qui rend la collaboration avec Claude Code fiable. | Frontend, backend, API, scripts projet. |
| Python | Prototypage rapide, data processing, scripts d'import/analyse, ML/IA. Reste le meilleur langage pour manipuler des données et explorer des idées rapidement. | Scripts utilitaires, pipelines de données, prototypage backend (MVP EVQuest). Ne pas utiliser pour le backend production d'un SaaS web — TypeScript + Next.js couvrent ce besoin. |
| Rust | Performance critique et protection de propriété intellectuelle. Le code compilé Rust est opaque à la rétro-ingénierie, contrairement à Python (bytecode décompilable) et JavaScript (lisible). | Tauri commands (desktop), logique métier sensible, tout module distribué où la protection IP est un enjeu. Voir knowledge/references/ip-protection-software.md. |
Couche Frontend
| Besoin | Outil retenu | Alternative | Pourquoi ce choix / Pourquoi pas l'alternative |
|---|---|---|---|
| Framework | Next.js 16 (App Router) | Astro | Next.js couvre SSR, SSG, Server Components, API Routes dans un seul framework. Astro est meilleur pour les sites 100% statiques (blogs, docs) mais ne couvre pas les apps interactives. |
| Styling | Tailwind CSS 4 (@theme tokens) |
CSS Modules | Tailwind 4 avec @theme centralise les design tokens en CSS natif. CSS Modules isole bien le scope mais ne fournit pas de système de tokens, ce qui mène à des valeurs hardcodées partout. |
| Composants base | shadcn/ui + Radix UI | Headless UI | shadcn/ui donne le code source complet (pas une dépendance npm) + accessibilité Radix. Headless UI est plus léger mais l'écosystème de composants prêts à l'emploi est bien plus petit. |
| Composants premium | Aceternity UI | Magic UI, ReactBits | Aceternity pour les hero sections et effets "wow". Magic UI pour les composants SaaS (pricing, features). ReactBits pour les micro-interactions. Les trois sont complémentaires, mais Aceternity est le point d'entrée par défaut. |
| Inspiration / Registry | 21st.dev | — | Registry de composants shadcn installables. Pas d'alternative équivalente à ce jour. |
| Animations | Framer Motion (Motion) | CSS animations natives | Framer Motion gère les transitions de layout, les animations scroll-triggered, et le prefers-reduced-motion de façon déclarative. Les animations CSS natives suffisent pour les micro-interactions simples (hover, focus). |
| Icônes | Phosphor Icons (duotone) | Lucide | Phosphor offre 6 poids par icône (thin → fill) ce qui permet une hiérarchie visuelle. Lucide est le défaut de shadcn/ui — fonctionnel mais générique, signal d'AI slop quand utilisé seul. |
| Typographie | Satoshi / DM Sans / Geist | — | Voir frontend-anti-slop-playbook.md Section 2 pour le catalogue complet. Ne JAMAIS utiliser Inter, Roboto, Arial par défaut — c'est le signal #1 d'AI slop. Le choix de fonts se fait en Phase 1 (brief créatif). |
Couche Backend
| Besoin | Outil retenu | Alternative | Pourquoi ce choix / Pourquoi pas l'alternative |
|---|---|---|---|
| BDD | PostgreSQL (via Supabase) | Neon, Vercel Postgres | Supabase bundle PostgreSQL + auth + storage + realtime + RLS dans un seul service avec un free tier généreux. Neon est excellent pour le serverless pur (branching, auto-scaling) mais ne fournit que la BDD. Vercel Postgres est un wrapper Neon sans valeur ajoutée propre. |
| ORM | Drizzle ORM | Prisma | Drizzle est TypeScript-first, code-first (pas de génération), bundle minimal (~7KB), natif edge/serverless. Prisma 7 a éliminé le moteur Rust et réduit l'écart de perf, mais garde l'étape prisma generate et un bundle plus lourd. Pour un vibe coder, le zéro-generation-step de Drizzle est un gain réel : les types se mettent à jour en sauvegardant le fichier. |
| Auth | Better-Auth | Clerk | Better-Auth est open source, TypeScript-first, maintient désormais Auth.js/NextAuth. Pas de pricing par utilisateur, pas de vendor lock-in. Clerk offre une DX supérieure (UI pré-construite, setup 5 min) mais coûte $0.02/MAU après 10K et crée une dépendance service. Supabase Auth est un 3e choix valide si le projet utilise déjà Supabase à fond (RLS, realtime). |
| API | Next.js API Routes + Server Actions | tRPC | Les API Routes et Server Actions couvrent 90% des besoins d'un SaaS. tRPC ajoute du type-safety end-to-end mais c'est une couche supplémentaire — à considérer uniquement si l'app a une API consommée par plusieurs clients. |
Couche Services
| Besoin | Outil retenu | Alternative | Pourquoi ce choix / Pourquoi pas l'alternative |
|---|---|---|---|
| Paiements | Stripe | Polar | Stripe est le standard de l'industrie : documentation exhaustive, gestion abonnements/factures/webhooks mature, support mondial. Polar est plus simple et orienté créateurs/open source mais l'écosystème est plus restreint. Pour un SaaS B2C/B2B, Stripe reste le choix par défaut. |
| Emails transactionnels | Resend | SendGrid | Resend a une DX moderne (SDK TypeScript natif, React Email pour les templates). SendGrid est plus ancien et plus complet pour le marketing email mais l'API est datée. |
| Analytics | PostHog | Vercel Analytics | PostHog est open source, auto-hébergeable, et inclut feature flags + session replays + A/B testing. Vercel Analytics est plus simple mais limité aux métriques de base (Core Web Vitals, trafic). |
| Error tracking | Sentry | — | Standard de l'industrie, free tier généreux, SDK Next.js officiel. Pas d'alternative qui justifie un changement. |
| AI SDK | Vercel AI SDK | LangChain.js | Le Vercel AI SDK est le standard pour intégrer des LLM dans Next.js : streaming natif, tool calling, support multi-provider (Anthropic, OpenAI, etc.), React hooks dédiés (useChat, useCompletion). LangChain.js est plus complet pour les pipelines RAG complexes mais apporte une abstraction lourde et souvent inutile pour un SaaS qui consomme simplement une API LLM. À inclure dans la stack uniquement si le produit intègre de l'IA côté utilisateur. |
Couche Infrastructure
| Besoin | Outil retenu | Alternative | Pourquoi ce choix / Pourquoi pas l'alternative |
|---|---|---|---|
| Déploiement | Vercel | Railway, Netlify | Vercel est le créateur de Next.js — intégration native, preview deployments, edge functions. Railway est mieux pour les backends non-Next.js (Python, Rust). Netlify a perdu du terrain sur les fonctionnalités edge. |
| CI/CD | GitHub Actions + Vercel auto-deploy | GitLab CI | GitHub Actions est natif à l'écosystème (même plateforme que le code) et Vercel auto-deploy sur chaque push rend le pipeline quasi-invisible. Les checks de lint, type-check et tests tournent dans les Actions ; le deploy est automatique. GitLab CI est plus puissant pour les pipelines complexes multi-étapes mais surdimensionné ici. |
| DNS | Cloudflare | — | Free, rapide, protection DDoS incluse. Pas de raison d'aller ailleurs. |
| Domaines | Namecheap | Cloudflare Registrar | Namecheap a l'interface la plus simple et des prix compétitifs. Cloudflare Registrar est au prix coûtant mais l'UX de gestion est plus confuse. |
| Cache / KV | Upstash (Redis) | Vercel KV | Upstash est serverless-native avec un free tier généreux et un pricing pay-per-request. Vercel KV est un wrapper Upstash sans valeur ajoutée propre. |
| Vector DB | Pinecone | Supabase pgvector | Pinecone est le leader pour le RAG et les embeddings avec un free tier fonctionnel. Supabase pgvector évite un service supplémentaire si la BDD est déjà Supabase, mais les performances sont inférieures à un vecteur DB dédié pour les gros volumes. |
Couche Testing
| Besoin | Outil retenu | Alternative | Pourquoi ce choix / Pourquoi pas l'alternative |
|---|---|---|---|
| Tests unitaires / intégration | Vitest | Jest | Vitest est natif Vite (donc compatible Next.js), supporte TypeScript sans config, et tourne significativement plus vite que Jest grâce au HMR. Jest reste le défaut historique mais nécessite plus de configuration pour TypeScript et ESM. |
| Tests E2E | Playwright | Cypress | Playwright supporte multi-navigateurs (Chromium, Firefox, WebKit) nativement, tourne en parallèle par défaut, et son mode codegen génère les tests en enregistrant les interactions. Cypress a une meilleure DX pour le debugging visuel mais ne supporte que Chromium nativement et les tests parallèles sont payants. |
Le testing n'est pas optionnel, c'est ce qui permet à Claude Code de refactoriser sans casser l'existant. Sans couverture de tests, chaque modification est un pari. Priorité minimale pour tout projet : tests unitaires sur la logique métier critique + tests E2E sur les parcours utilisateur principaux (signup, login, flux de paiement).
Couche Légal & Conformité
Le cadrage légal fait partie du scope dès la Phase 1 (Concevoir), pas en afterthought. Tout projet déployé en France ou servant des utilisateurs EU est soumis au RGPD.
| Besoin | Outil / Approche | Notes |
|---|---|---|
| Cookie consent | Tarteaucitron.js ou CookieConsent (Orestbida) | Solutions open source, RGPD-compliant, intégrables dans Next.js. Le bandeau cookies est une obligation légale, pas une option. |
| Politique de confidentialité | Rédaction assistée + validation juridique | Claude peut aider à rédiger un draft, mais un document légal destiné à la production doit être validé par un professionnel. Ne pas publier de mentions légales générées par IA sans review humaine qualifiée. |
| Mentions légales | Obligatoires (loi française) | Nom/raison sociale, hébergeur, contact, numéro SIRET si applicable. À intégrer dès le premier déploiement public. |
| CGV / CGU | À rédiger si vente de service | Obligatoires dès qu'il y a une transaction commerciale. Stripe exige aussi des conditions de remboursement. |
| Audit dépendances | npm audit + Snyk (free tier) |
Vérification automatique des vulnérabilités dans les dépendances. Intégrable dans le CI/CD via GitHub Actions. Snyk offre un monitoring continu gratuit pour les projets open source. |
| Headers de sécurité | next.config.js + Vercel headers |
CSP, X-Frame-Options, HSTS, X-Content-Type-Options. Configurables dans Next.js et/ou au niveau Vercel. Vérifiables sur securityheaders.com. |
Couche Distribution
Cette section s'applique quand le projet atteint un stade de maturité suffisant pour être distribué à des utilisateurs. Ce n'est pas une priorité de Phase 1 — c'est une étape finalisante.
| Besoin | Outil retenu | Alternative | Pourquoi ce choix / Pourquoi pas l'alternative |
|---|---|---|---|
| Documentation produit | Fumadocs | Nextra, Mintlify | Fumadocs est construit sur Next.js (même stack, même déploiement), avec un rendu MDX natif et une recherche intégrée. Nextra est aussi Next.js mais moins activement maintenu. Mintlify offre un hébergement managed avec une belle DX mais c'est un service payant et propriétaire. |
| Changelog public | Page custom ou GitHub Releases | — | Pour un SaaS, une page changelog dans l'app est plus visible pour les utilisateurs que les GitHub Releases. Le format peut être simple : date + titre + description courte. |
| Desktop packaging (EVQuest) | PyInstaller + NSIS → Tauri bundler | Electron Builder | PyInstaller + NSIS pour la phase actuelle Python. Migration vers le Tauri bundler quand la logique métier sera en Rust. Electron Builder est le standard Electron mais ne s'applique pas à la stack Tauri. |
Coût mensuel estimé (stack complète SaaS)
La quasi-totalité de la stack a un free tier fonctionnel pour le MVP et les premiers utilisateurs. Le seul coût incompressible est l'abonnement Claude ($20/mois). Les coûts à anticiper à scale : Supabase Pro ($25/mois au-delà du free tier), Vercel Pro ($20/mois si les limites du free tier sont atteintes), Stripe (2.9% + $0.30 par transaction).
Exception : projet perso privacy-critique
Le défaut Supabase + Vercel est calibré pour les SaaS. Un projet perso, non commercial, manipulant des données très sensibles (bancaires, santé, journal intime, engagement de couple) où la confidentialité est une condition fondatrice justifie une déviation ciblée — le registre l'autorise déjà (« l'alternative est légitime quand le contexte l'exige ») :
- BDD : PostgreSQL auto-hébergé (Docker sur VPS contrôlé), au lieu de Supabase managé.
- Déploiement : VPS FR/UE (OVH / Scaleway / Hetzner) + Docker, au lieu de Vercel.
Le reste de la stack est conservé tel quel (Next.js, TypeScript, Tailwind, shadcn/ui, Drizzle, Better-Auth…). On ne change que le lieu d'hébergement, pas le moteur : PostgreSQL reste le bon choix multi-utilisateur (cf. database-choice-criteria.md), Drizzle et Better-Auth tournent sur n'importe quel Postgres. Ne PAS auto-héberger Supabase complet (10+ conteneurs, ~8 Go RAM) — faux compromis à petite échelle, Postgres nu + app suffit. Cette exception ne s'applique PAS aux SaaS : pour eux, Supabase/Vercel reste le défaut.
Vécu : ToGather — juin 2026.
Anti-patterns à éviter
"On commence avec SQLite / localStorage et on migrera plus tard." Non. La migration coûte toujours plus que de bien commencer. Supabase PostgreSQL est gratuit — il n'y a aucune raison d'utiliser une solution inférieure.
"On utilisera React + Vite pour aller plus vite." Non. Next.js 16 offre le même DX avec le SSR, le SEO, les Server Components et les API Routes en plus. Vite seul est un sous-ensemble de ce que Next.js fournit.
"On utilisera Prisma parce que Claude le connaît mieux." Non. Claude Code connaît aussi bien Drizzle que Prisma. Le choix d'ORM se fait sur les critères techniques (bundle size, edge compatibility, generation step), pas sur la familiarité présumée de l'agent.
"On n'a pas besoin d'auth pour le MVP." Si le produit a des utilisateurs, il a besoin d'auth. Better-Auth + une page de login, c'est une session de dev. Rajouter l'auth après coup sur une app qui n'a pas été conçue pour, c'est un refactoring de plusieurs jours.
"On utilisera Inter / Roboto pour la typo." Non. Voir le playbook anti-slop. La typographie est le signal #1 de qualité perçue. Choisir des fonts en Phase 1, pas après.
"Le légal c'est pour plus tard." Non. Les mentions légales et la politique de confidentialité sont obligatoires dès le premier déploiement public en France/EU. Un bandeau cookies mal implémenté ou absent expose à des sanctions CNIL. Intégrer le cadrage légal dès la Phase 1.
"On écrira les tests à la fin." Non. Les tests sur la logique métier critique se mettent en place dès que cette logique existe. Sans eux, chaque refactoring par Claude Code est un risque de régression silencieuse.
Ce document évolue avec l'expérience projet. Chaque ajout ou modification doit être justifié par du vécu, pas par du marketing. Dernière vérification des outils : juin 2026.
Dernière mise à jour : juin 2026