1-1-project-scaffold-avec-t3-et-shadcn-ui.md 14 KB

Story 1.1: Project scaffold avec T3 et shadcn/ui

Status: done

Story

En tant que développeur, je veux initialiser le projet avec create-t3-app et shadcn/ui, afin d'avoir une base Next.js, Prisma, tRPC, NextAuth et design system prêts à recevoir le schéma multi-tenant (Story 1.2) et les composants métier (Stories suivantes).

Acceptance Criteria (AC)

  1. Given le répertoire projet actuel (AImpact-Ai_Hub/) When j'exécute le scaffold T3 avec les flags spécifiés Then un sous-dossier projet (ou le dossier courant) contient Next.js App Router, TypeScript strict, Tailwind CSS, tRPC, Prisma (provider postgres), NextAuth And pnpm dev démarre sans erreur et affiche la page d'accueil T3

  2. Given le projet T3 scaffoldé When j'exécute npx shadcn@latest init avec les options alignées sur la spec UX Then components.json est créé à la racine And src/lib/utils.ts contient la fonction cn() (class merge helper) And src/app/globals.css contient les CSS variables de theming shadcn

  3. Given shadcn/ui initialisé When j'ajoute un composant de test (npx shadcn@latest add button) Then le fichier src/components/ui/button.tsx est créé And le composant est importable et s'affiche sans erreur dans pnpm dev

  4. Given le projet complet (T3 + shadcn) When je vérifie la structure de fichiers Then elle correspond à la structure documentée dans l'architecture (voir section File Structure ci-dessous) And .env.example existe avec les variables documentées (sans secrets) And prisma/schema.prisma contient le provider postgresql et les modèles NextAuth par défaut

  5. Given le projet complet When j'exécute pnpm build Then le build réussit sans erreur TypeScript ni warning critique

Tasks / Subtasks

  • Task 1 : Scaffold T3 (AC: #1, #4)
    • 1.1 S'assurer que pnpm est installé (pnpm --version)
    • 1.2 Exécuter : pnpm dlx create-t3-app@latest --CI --trpc --prisma --nextAuth --tailwind --appRouter --dbProvider postgres
    • 1.3 Si le CLI crée un sous-dossier : déplacer le contenu à la racine du projet OU travailler dans le sous-dossier — documenter le choix
    • 1.4 Exécuter pnpm install si les dépendances n'ont pas été installées
    • 1.5 Vérifier pnpm dev — la page d'accueil T3 s'affiche sur localhost:3000
    • 1.6 Vérifier pnpm build — build sans erreur
  • Task 2 : Configurer .env (AC: #4)
    • 2.1 Créer .env à partir de .env.example avec des valeurs de développement local
    • 2.2 DATABASE_URL : utiliser une URL PostgreSQL locale ou placeholder — la connexion Neon sera configurée en Story 1.2
    • 2.3 NEXTAUTH_SECRET : générer avec openssl rand -base64 32
    • 2.4 NEXTAUTH_URL : http://localhost:3000
    • 2.5 Vérifier que .env est dans .gitignore
  • Task 3 : Init shadcn/ui (AC: #2, #3)
    • 3.1 Exécuter npx shadcn@latest init
    • 3.2 Pendant l'init, choisir : style Default (ou New York), CSS variables Yes, base color Slate (sera remplacé par Livinia en Story 1.2)
    • 3.3 Vérifier que components.json est créé
    • 3.4 Vérifier que src/lib/utils.ts contient cn()
    • 3.5 Ajouter le composant Button : npx shadcn@latest add button
    • 3.6 Vérifier que src/components/ui/button.tsx existe et est importable
    • 3.7 Optionnel : ajouter Card (npx shadcn@latest add card) pour valider
  • Task 4 : Vérification finale (AC: #5)
    • 4.1 pnpm dev fonctionne
    • 4.2 pnpm build réussit
    • 4.3 Structure de fichiers conforme (voir section ci-dessous)
    • 4.4 .env.example documenté

Dev Notes

Contexte projet

AImpact Hub est un SaaS B2B d'accélération de la culture IA en entreprise. Cette story est le tout premier scaffold — aucun code n'existe encore. Le projet sera multi-tenant (workspace_id sur toutes les tables), avec deux personas : le Transformateur (CDO, authentifié NextAuth) et le Contributeur (accès public sans compte, via /submit/[workspaceSlug]).

Décisions d'architecture déjà prises

Ces choix sont figés — ne pas les remettre en question :

Décision Choix Source
Framework Next.js App Router Architecture doc
ORM Prisma avec PostgreSQL Architecture doc
API tRPC (interne) + Route Handlers (webhooks, LLM) Architecture doc
Auth NextAuth.js 4.x (Prisma adapter) Architecture doc
Styling Tailwind CSS + shadcn/ui (Radix) Architecture + UX spec
Package manager pnpm Architecture doc
DB provider Neon eu-central-1 (Frankfurt) Architecture doc
Design tokens Livinia Chaleureux (#fefdfb, #7c3aed) UX spec
Hébergement Vercel (EU region) Architecture doc

Ce que cette story produit

  • Un projet T3 fonctionnel avec pnpm dev et pnpm build
  • shadcn/ui initialisé avec au moins Button disponible
  • .env.example documenté
  • Le schéma Prisma par défaut de T3 (modèles NextAuth) — non modifié

Ce que cette story ne fait PAS

  • Pas de modèles Prisma custom (Workspace, Idea, Contributor) — Story 1.2
  • Pas de migration DB ni connexion à Neon — Story 1.2
  • Pas de design tokens Livinia (palette couleurs, CSS variables custom) — Story 1.2
  • Pas de composants métier (IdeaCard, KanbanBoard, etc.) — Stories 2+
  • Pas de pages ou routes métier — Stories suivantes
  • Pas de Vitest — à ajouter ultérieurement

Points d'attention critiques

  1. Répertoire de travail : create-t3-app crée un sous-dossier par défaut (nommé d'après le projet). En mode --CI, le nom par défaut est utilisé. Décider si on travaille dans le sous-dossier ou si on déplace le contenu à la racine. Documenter le choix.

  2. Le flag --CI est obligatoire pour éviter les prompts interactifs. Sans --CI, les flags --trpc, --prisma, etc. sont ignorés.

  3. shadcn/ui init APRÈS T3 — jamais l'inverse. L'init détecte la config Tailwind existante.

  4. CSS variables = Yes lors du shadcn init — indispensable pour le theming Livinia Chaleureux qui sera appliqué en Story 1.2.

  5. Ne PAS restructurer src/app/, src/server/, src/lib/ — la structure T3 par défaut est conforme à l'architecture cible.

  6. Ne PAS modifier prisma/schema.prisma — le schéma multi-tenant sera défini en Story 1.2.

Project Structure Notes

Structure attendue après scaffold T3 + shadcn init :

aimpact-hub/                          (ou racine projet)
├── .env.example
├── .env                              (local, gitignored)
├── .eslintrc.cjs
├── .gitignore
├── components.json                   ← shadcn config
├── next.config.js
├── package.json
├── pnpm-lock.yaml
├── tailwind.config.ts
├── tsconfig.json
├── prisma/
│   └── schema.prisma                 ← modèles NextAuth par défaut, provider postgresql
├── public/
├── src/
│   ├── app/
│   │   ├── globals.css               ← CSS variables shadcn injectées ici
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   └── ui/
│   │       └── button.tsx            ← ajouté via `npx shadcn add button`
│   ├── lib/
│   │   └── utils.ts                  ← cn() helper (shadcn)
│   ├── server/
│   │   ├── auth.ts
│   │   ├── db.ts
│   │   └── api/
│   │       ├── root.ts
│   │       └── trpc.ts
│   ├── styles/                       ← (sera créé en Story 1.2 pour les tokens Livinia)
│   └── trpc/                         ← client tRPC (React Query)

.env.example attendu

# Base de données — PostgreSQL (Neon eu-central-1 en production)
DATABASE_URL="postgresql://user:password@localhost:5432/aimpact_hub?schema=public"

# NextAuth
NEXTAUTH_SECRET="generate-with-openssl-rand-base64-32"
NEXTAUTH_URL="http://localhost:3000"

# Auth (décision 2026-02-27 : email + password, pas d'OAuth)
# Le provider Discord fourni par T3 n'est PAS utilisé — Story 1.2b implémente Credentials (email/password + confirmation)

References

  • [Source: _bmad-output/planning-artifacts/architecture.md#Starter-Template-Evaluation]
  • [Source: _bmad-output/planning-artifacts/architecture.md#Initialization-Command]
  • [Source: _bmad-output/planning-artifacts/architecture.md#Project-Structure-and-Boundaries]
  • [Source: _bmad-output/planning-artifacts/architecture.md#Implementation-Patterns]
  • [Source: _bmad-output/planning-artifacts/ux-design-specification.md#Design-System-Foundation]
  • [Source: _bmad-output/planning-artifacts/epics.md#Story-1.1]

Developer Context — Guardrails agent Dev

Commandes exactes (NE PAS MODIFIER)

# Step 1 — Scaffold T3
pnpm dlx create-t3-app@latest --CI --trpc --prisma --nextAuth --tailwind --appRouter --dbProvider postgres

# Step 2 — Init shadcn/ui (dans le dossier projet)
npx shadcn@latest init

# Step 3 — Ajouter composant de validation
npx shadcn@latest add button

Choix shadcn/ui init

Quand npx shadcn@latest init pose des questions :

Question Réponse Raison
Style Default (ou New York) Sera remplacé par Livinia en 1.2
Base color Slate Sera remplacé par palette crème/violet en 1.2
CSS variables Yes Obligatoire pour le theming Livinia Chaleureux
Where is your global CSS file? src/app/globals.css Détecté auto par T3
Import alias @/* ou ~/ Garder celui de T3

Anti-patterns — NE PAS FAIRE

Anti-pattern Pourquoi
Modifier prisma/schema.prisma Story 1.2 — schéma multi-tenant
Ajouter des pages ou routes métier Stories suivantes
Installer des dépendances supplémentaires (dnd-kit, etc.) Chaque story installe ses propres dépendances
Restructurer src/ (renommer server/, lib/, etc.) La structure T3 est conforme à l'architecture cible
Supprimer les exemples T3 (page d'accueil, etc.) Sera nettoyé en Story 1.2/1.3 quand les vraies pages arrivent
Configurer la palette Livinia Chaleureux Story 1.2 — design tokens
Créer des composants custom Stories suivantes
Modifier next.config.js (sauf si build échoue) Configuration par défaut suffisante
Utiliser npm ou yarn au lieu de pnpm pnpm est le package manager du projet

Pièges connus create-t3-app

  1. Sous-dossier créé automatiquement : create-t3-app crée un dossier nommé (ex. my-t3-app/). En mode --CI, le nom par défaut est utilisé. Si le CLI demande un nom, répondre aimpact-hub.
  2. --CI obligatoire : sans ce flag, les autres flags (--trpc, --prisma, etc.) sont ignorés et le CLI devient interactif.
  3. Prisma sans DB : pnpm dev fonctionne sans base PostgreSQL connectée, mais prisma db push échouera — normal, c'est Story 1.2.
  4. NextAuth sans provider : T3 configure Discord par défaut. Login échouera sans config — normal. Story 1.2b implémente l'auth email/password + confirmation (provider Credentials). Pas d'OAuth (Discord, Google) en MVP.

Pièges connus shadcn/ui

  1. init vs create : npx shadcn@latest create est pour un nouveau projet from scratch. Pour un projet T3 existant → toujours npx shadcn@latest init.
  2. Détection Tailwind : shadcn détecte la config Tailwind existante. Si erreur, vérifier que tailwind.config.ts existe.
  3. cn() helper : shadcn crée src/lib/utils.ts avec la fonction cn() qui merge les classes Tailwind. Si le fichier existe déjà (T3 en crée un), shadcn le modifie. Vérifier qu'il contient bien cn().

Library & Framework versions

Bibliothèque Version attendue Notes
create-t3-app v7.40+ pnpm dlx create-t3-app@latest
Next.js 14+ ou 15+ (fourni par T3) App Router, Turbopack
TypeScript 5.x (fourni par T3) Strict mode activé
Tailwind CSS 3.x ou 4.x (fourni par T3) Config dans tailwind.config.ts
Prisma 5.x ou 6.x (fourni par T3) Provider PostgreSQL
NextAuth.js 4.x (fourni par T3) Prisma adapter
shadcn/ui @latest Via CLI npx shadcn@latest
React 18+ (fourni par T3) Server Components support

Authentification (décision produit 2026-02-27)

L'auth Transformateur utilise email + mot de passe avec confirmation par email. Pas d'OAuth (Google, Discord). Story 1.2b implémente : inscription → confirmation email → connexion (NextAuth Credentials). Story 1.3 (création workspace) s'exécute après première connexion.

Ce que Story 1.2 attend de cette story

Story 1.2 (Schéma Prisma Workspace et modèle multi-tenant) prendra le relais avec :

  • Modification de prisma/schema.prisma pour ajouter Workspace, Idea, Contributor, etc.
  • Configuration DATABASE_URL vers Neon eu-central-1
  • prisma db push ou prisma migrate
  • Application des design tokens Livinia Chaleureux dans globals.css
  • Configuration de createWorkspaceProcedure pour l'isolation multi-tenant

Pour que Story 1.2 fonctionne, cette story DOIT livrer :

  • Un prisma/schema.prisma fonctionnel avec provider postgresql
  • Un src/server/db.ts avec le Prisma client configuré
  • Un src/server/api/trpc.ts avec la base tRPC
  • Un components.json avec CSS variables activées
  • Un globals.css avec les CSS variables shadcn (base pour le theming)

Vérification finale — checklist dev

[ ] pnpm dev démarre → localhost:3000 affiche la page T3
[ ] pnpm build → succès, 0 erreur TypeScript
[ ] components.json existe à la racine
[ ] src/components/ui/button.tsx existe
[ ] src/lib/utils.ts contient cn()
[ ] prisma/schema.prisma → provider = "postgresql"
[ ] .env.example documenté
[ ] .env dans .gitignore
[ ] Aucun modèle Prisma custom ajouté
[ ] Aucune dépendance supplémentaire installée

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

  • T3 v7.40 scaffoldé dans aimpact-hub/ (sous-dossier). NextAuth v5 beta, Tailwind v4.
  • shadcn/ui init avec CSS variables. Button ajouté. globals.css dans src/styles/ (T3 v7).
  • env.js : AUTH_DISCORD_ID/SECRET rendus optionnels (auth email/password en Story 1.2b).
  • .env.example mis à jour (auth Credentials, pas Discord).

File List

  • aimpact-hub/ (projet T3 complet)
  • aimpact-hub/src/env.js (modifié — Discord optionnel)
  • aimpact-hub/.env.example (modifié — auth Credentials)