L
Logo
🌐FRfrançais

Guide de Démarrage - Next SaaS Starter

Vous souhaitez construire une application SaaS avec Next.js sans passer des semaines sur le code de base ? Ce guide vous explique tout ce que vous devez savoir sur le template next-saas-starter : ce qu'il contient, comment il fonctionne, et comment configurer votre environnement de developpement.

Qu'est-ce que next-saas-starter ?

next-saas-starter est un template de demarrage pour la creation d'applications SaaS. Il regroupe une stack technique moderne pour que vous puissiez vous concentrer sur votre produit au lieu de passer du temps sur l'infrastructure.

Voici ce qui est inclus :

  • Next.js 16 avec l'App Router et React 19
  • TypeScript 5.9 pour la surete des types
  • Tailwind CSS 4 avec DaisyUI 5 pour le theming et les composants UI
  • Better Auth pour l'authentification (Google OAuth, liens magiques)
  • Convex comme backend temps reel et base de donnees
  • Stripe pour les paiements et abonnements
  • next-intl pour l'internationalisation (anglais et francais)
  • Content Collections avec validation Zod pour les articles de blog et les pages
  • Vitest avec React Testing Library pour les tests
  • Docker pour le deploiement containerise

Prerequis

Avant de commencer, assurez-vous que les outils suivants sont installes sur votre machine :

  • Node.js 20 ou superieur — Verifiez avec node -v
  • npm — Fourni avec Node.js
  • Git — Pour cloner le depot

Optionnel mais recommande :

  • Docker — Si vous prevoyez un deploiement containerise
  • Stripe CLI — Pour tester les webhooks en local

Installer Node.js

Si vous n'avez pas Node.js 20+ installe, la methode la plus simple est d'utiliser un gestionnaire de versions :

# Avec nvm (macOS/Linux)
nvm install 20
nvm use 20

# Avec fnm (multi-plateforme)
fnm install 20
fnm use 20

Vous pouvez aussi telecharger Node.js directement depuis nodejs.org.

Cloner et installer

Clonez le depot et installez les dependances :

git clone https://github.com/nicosql/next-saas-base.git
cd next-saas-base
npm install

Cela installe toutes les dependances listees dans package.json, y compris Next.js, React, Tailwind CSS, et le reste de la stack.

Configuration de l'environnement

Copiez le fichier d'environnement d'exemple pour creer votre configuration locale :

cp .env.example .env.local

Ouvrez .env.local dans votre editeur et remplissez les valeurs necessaires :

Variables requises

# URL de votre application (localhost pour le developpement)
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Secret d'authentification — generez-en un avec : openssl rand -base64 32
AUTH_SECRET=votre-secret-genere-ici

Authentification (optionnel)

# Google OAuth
AUTH_GOOGLE_ID=votre-google-client-id
AUTH_GOOGLE_SECRET=votre-google-client-secret

# Emails par lien magique via Resend
AUTH_RESEND_KEY=votre-cle-api-resend

Backend Convex

# Ces valeurs sont fournies quand vous liez votre projet Convex
CONVEX_DEPLOYMENT=votre-deployment-convex
NEXT_PUBLIC_CONVEX_URL=https://votre-projet.convex.cloud

Paiements Stripe (optionnel)

STRIPE_TEST_SECRET_KEY=sk_test_...
STRIPE_TEST_WEBHOOK_SECRET=whsec_...
STRIPE_TEST_PRICE_ID=price_...

Vous n'avez pas besoin de configurer toutes les variables pour commencer a developper. Au minimum, definissez NEXT_PUBLIC_APP_URL et AUTH_SECRET.

Configurer Convex

Ce projet utilise Convex comme backend. Pour connecter votre environnement local :

npx convex dev

Cette commande va :

  1. Vous demander de vous connecter a Convex (ou de creer un compte)
  2. Lier votre projet local a un deploiement Convex
  3. Synchroniser le schema de la base de donnees
  4. Surveiller les changements en continu

Gardez cette commande active dans un terminal separe pendant le developpement.

Lancer le serveur de developpement

Une fois votre environnement configure, lancez le serveur :

npm run dev

Ouvrez http://localhost:3000 dans votre navigateur. Vous devriez voir la page d'accueil avec la navigation, une section hero et le blog.

Le serveur de developpement utilise Turbopack pour un rafraichissement rapide — les modifications que vous apportez a votre code apparaissent presque instantanement dans le navigateur.

Structure du projet

Voici un apercu des repertoires principaux :

app/                    # App Router Next.js
├── [locale]/           # Routage par langue (en, fr)
│   ├── (main)/         # Groupe de routes principal (blog, pages)
│   └── layout.tsx      # Layout avec next-intl
└── api/                # Routes API

components/             # Composants React (design atomique)
├── ui/                 # Primitives de base (boutons, inputs, dialogues)
├── atoms/              # Petits composants reutilisables
├── molecules/          # Composants composes
├── organisms/          # Grandes sections (header, footer)
└── providers/          # Fournisseurs de contexte

lib/                    # Utilitaires et logique principale
├── auth.ts             # Configuration de l'authentification
├── content/            # Couche de donnees du contenu
├── i18n/               # Utilitaires d'internationalisation
├── hooks/              # Hooks React personnalises
├── seo/                # Generateurs de metadonnees SEO
└── utils.ts            # Utilitaire cn() pour la fusion de classes

config/                 # Configuration de l'application
├── site.config.ts      # Nom du site, URL, description
├── i18n.config.ts      # Langues supportees
├── stripe.config.ts    # Configuration des plans Stripe
├── routes.config.ts    # Definitions des routes
└── features.config.ts  # Flags de fonctionnalites

content/                # Contenu Markdown (Content Collections)
├── posts/en/           # Articles de blog en anglais
├── posts/fr/           # Articles de blog en francais
└── pages/              # Pages statiques

messages/               # Fichiers de traduction i18n
├── en.json             # Anglais
└── fr.json             # Francais

Concepts cles

  • Design atomique : Les composants sont organises du plus petit (atoms/) au plus grand (organisms/)
  • Routage par langue : Toutes les pages vivent sous app/[locale]/ pour le support automatique des langues
  • Server Components : Les pages sont des composants serveur asynchrones par defaut — les composants client utilisent la directive "use client" uniquement quand c'est necessaire
  • Couleurs semantiques : Utilisez les couleurs DaisyUI (primary, secondary, base-100) au lieu des couleurs Tailwind brutes — elles s'adaptent automatiquement aux themes

Commandes essentielles

Voici les commandes que vous utiliserez le plus souvent :

# Developpement
npm run dev              # Lancer le serveur de dev (port 3000)

# Qualite du code
npm run lint             # Lancer ESLint
npm run typecheck        # Verification des types TypeScript
npm test                 # Lancer les tests (execution unique)
npm run test:watch       # Lancer les tests en mode surveillance

# Build et production
npm run build            # Build de production
npm start                # Lancer le serveur de production

# Pipeline CI complet (ce qui tourne dans GitHub Actions)
npm run ci               # lint + typecheck + test + build

# Verification complete de la qualite
npm run check:quality    # oxfmt + content + oxlint + typecheck + test + lint + build

Ecrire et lancer les tests

Les tests sont ecrits avec Vitest et React Testing Library. Les fichiers de tests se trouvent dans le repertoire __tests__/.

Pour lancer la suite de tests :

npm test

Pour lancer les tests en mode surveillance pendant le developpement :

npm run test:watch

Un test basique ressemble a ceci :

import { render, screen } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";

// Mocker next-intl pour les composants qui utilisent les traductions
vi.mock("next-intl", () => ({
  useTranslations: () => (key: string) => key,
}));

describe("MonComposant", () => {
  it("s'affiche correctement", () => {
    render(<MonComposant />);
    expect(screen.getByText("texte attendu")).toBeInTheDocument();
  });
});

Deploiement Docker (optionnel)

Le projet inclut un Dockerfile multi-etapes pour le deploiement en production. Pour construire et lancer avec Docker :

# Construire l'image
docker build -t next-saas-starter .

# Lancer le conteneur
docker run -p 3000:3000 next-saas-starter

L'image Docker utilise node:20-alpine et produit un build standalone minimal.

Prochaines etapes

Maintenant que votre environnement est en place, voici quelques pistes a explorer :

  1. Personnaliser votre site — Editez config/site.config.ts pour definir le nom, l'URL et la description de votre application
  2. Ajouter des pages — Creez des routes sous app/[locale]/(main)/
  3. Configurer les produits Stripe — Creez des produits dans le Dashboard Stripe et ajoutez les IDs de prix dans votre .env.local
  4. Tester les webhooks Stripe — Utilisez le CLI Stripe en local : stripe listen --forward-to localhost:3000/api/stripe/webhook
  5. Ecrire du contenu — Ajoutez des fichiers markdown dans content/posts/en/ ou content/posts/fr/
  6. Ajouter des traductions — Editez messages/en.json et messages/fr.json pour les nouvelles chaines de l'interface
  7. Deployer — Le projet fonctionne avec Vercel, Docker, ou toute plateforme supportant Node.js

Bon developpement !

Derniers articles

Voir tous les articles