Construire un projet React fullstack de A à Z : architecture, stack, déploiement

Apprendre React en isolation est une chose. Construire un vrai projet fullstack qui tourne en production en est une autre. Ce guide vous montre l’architecture complète d’un projet React fullstack moderne : du choix de la stack aux décisions d’architecture, en passant par la structure de fichiers et le déploiement.

La stack fullstack React recommandée en 2026

• Framework : Next.js 15 (App Router) — gère le front, le back, et le routing en un seul projet
• Base de données : PostgreSQL avec Prisma (ORM TypeScript-first)
• Auth : Auth.js (anciennement NextAuth) — gestion de sessions, OAuth, JWT intégrée
• State management : Zustand (state UI) + TanStack Query (state serveur)
• Styling : Tailwind CSS + shadcn/ui (composants accessibles prêts à personnaliser)
• Tests : Vitest + Testing Library
• Déploiement : Vercel (Next.js) + Supabase ou Railway (PostgreSQL)

L’architecture d’un projet Next.js fullstack

my-app/
├── app/                        # Routes Next.js App Router
│   ├── layout.tsx              # Layout racine
│   ├── page.tsx                # Route /
│   ├── (auth)/                 # Route group — pas dans l'URL
│   │   ├── login/page.tsx      # Route /login
│   │   └── register/page.tsx   # Route /register
│   ├── dashboard/
│   │   ├── layout.tsx          # Layout protégé (vérif auth)
│   │   └── page.tsx            # Route /dashboard
│   └── api/                    # API Routes
│       ├── auth/[...nextauth]/route.ts
│       └── users/route.ts      # GET /api/users, POST /api/users
│
├── components/
│   ├── ui/                     # Composants génériques (Button, Input...)
│   └── features/               # Composants métier (UserCard, ProductList...)
│
├── lib/
│   ├── db.ts                   # Client Prisma singleton
│   ├── api.ts                  # Couche fetch client-side
│   └── auth.ts                 # Config Auth.js
│
├── server/                     # Code qui tourne UNIQUEMENT côté serveur
│   ├── actions/                # Server Actions Next.js
│   └── queries/                # Requêtes DB (Prisma)
│
├── prisma/
│   └── schema.prisma           # Schéma de la base de données
│
└── types/                      # Types TypeScript partagés

Les Server Actions — la nouveauté qui change tout

Avec Next.js 14+, vous pouvez appeler des fonctions serveur directement depuis vos composants React, sans créer une route API :

// server/actions/users.ts
'use server'
import { prisma } from '@/lib/db'
import { auth } from '@/lib/auth'

export async function createUser(formData: FormData) {
  const session = await auth()
  if (!session) throw new Error('Non authentifié')

  const name = formData.get('name') as string
  const email = formData.get('email') as string

  const user = await prisma.user.create({ data: { name, email } })
  revalidatePath('/dashboard/users') // invalide le cache de la page
  return user
}

// Utilisation dans un composant
import { createUser } from '@/server/actions/users'

export function CreateUserForm() {
  return (
    
  {/* Next.js appelle l'action directement */}
      
      
      Créer
    
  )
}

La couche base de données avec Prisma

// prisma/schema.prisma
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  role      Role     @default(USER)
  posts     Post[]
  createdAt DateTime @default(now())
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
}

enum Role { ADMIN USER }

// lib/db.ts — singleton pour éviter les connexions multiples en dev
import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient }
export const prisma = globalForPrisma.prisma ?? new PrismaClient()
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

// Requêtes typées
const users = await prisma.user.findMany({
  where: { role: 'ADMIN' },
  include: { posts: { where: { published: true } } },
  orderBy: { createdAt: 'desc' },
})

Le déploiement

Le setup le plus simple pour un projet de ce type en 2026 :

• Vercel : connectez votre repo GitHub, Next.js est déployé automatiquement à chaque push. Gratuit jusqu’à un certain trafic.
• Supabase : PostgreSQL managé avec interface, auth, et API REST en bonus. Plan gratuit généreux.
• Variables d’environnement : DATABASE_URL, NEXTAUTH_SECRET, clés API — à configurer dans le dashboard Vercel.

// .env.local (ne jamais commiter)
DATABASE_URL="postgresql://user:password@host:5432/mydb"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="un-secret-genere-avec-openssl-rand-base64-32"
GITHUB_CLIENT_ID="..."
GITHUB_CLIENT_SECRET="..."

# Commandes de démarrage
npm run db:push    # Sync le schéma Prisma avec la DB
npm run db:seed    # Remplir avec des données de test
npm run dev        # Lancer le serveur de développement

Ce projet dans votre portfolio

Un projet fullstack Next.js + PostgreSQL + Auth déployé sur Vercel vous distingue immédiatement des candidats qui n’ont que des projets front-end statiques. Ce que les recruteurs regardent : l’URL qui fonctionne, le code GitHub propre avec commits lisibles, et votre capacité à expliquer vos choix techniques.

---

À lire aussi : Next.js pour débutant — Fetch API et Axios — State management React