Le guide qui
démystifie ton code

Tu n'y connais rien en code ? Parfait. Ce guide t'explique tout comme une histoire : comment ton site fonctionne, où tout se trouve, et comment le faire évoluer. Pas de jargon inutile, que des réponses claires.

🔍
🛠

Comment tout s'organise

Imagine ton site comme un immeuble. Chaque étage a un rôle précis. Voici comment les pièces sont agencées.

👨‍💻
Toi (GitHub)
Tu modifies le code
➔
🔄
GitHub Actions
Vérifie + construit
➔
▲
Vercel
Héberge le site
➔
🌐
dixipolis.vercel.app
Les utilisateurs voient le site
💡
En résumé : tu modifies le code sur GitHub, GitHub Actions vérifie que tout est OK (pas d'erreurs), puis envoie automatiquement le site mis à jour sur Vercel. Tes visiteurs voient la dernière version en 2 minutes.
📁

Les fichiers du projet

Ton projet est organisé en dossiers comme un classeur bien rangé. Voici à quoi sert chaque « tiroir ».

📄

src/app/

Chaque sous-dossier = une page du site. src/app/analytique/page.tsx = la page /analytique. C'est aussi simple que ça.

Pages
🧩

src/components/

Les « briques » réutilisables : boutons, cartes, header, footer. Comme des pièces de Lego qu'on assemble dans les pages.

Composants
📚

src/lib/

Les fonctions utilitaires et les données mock. constants.ts contient toutes les données fictives du site (politiciens, contenus, etc.).

Utilitaires
🔐

src/types/

Les « plans » de données. Définit la forme de chaque objet (un article a un titre, un thème, une date...). Empêche les erreurs.

Types
🎨

src/app/globals.css

Le fichier de style central. Toutes les couleurs, ombres, animations sont définies ici comme des variables CSS réutilisables partout.

Style
📦

public/

Les fichiers statiques : images, favicons, et... ce guide ! Tout ce qui est dans public/ est accessible directement par URL.

Statique
⚡

Next.js — le moteur du site

Next.js, c'est le « moteur » qui fait tourner ton site. Il transforme tes fichiers TypeScript en pages web rapides et optimisées.

Next.js est un framework React créé par Vercel. Il prend tes fichiers de code et génère un site web ultra-rapide. La magie : il peut générer les pages à l'avance (statique) ou à la volée (dynamique).

Pour Dixipolis, la plupart des pages sont statiques (générées une seule fois), sauf la page /politicien/[slug] qui est dynamique (le contenu change selon le politicien).

Server Component = la page est construite côté serveur. Pas de JavaScript envoyé au navigateur. Plus rapide, plus léger. C'est le mode par défaut dans Next.js.

Client Component = la page a besoin d'interactivité (clics, formulaires, animations). On ajoute "use client" en haut du fichier. Exemples : ChatInterface, ContentFilter, Header.

Règle d'or : utilise « use client » uniquement quand c'est nécessaire (formulaires, états, effets).

C'est le routage par fichiers. Chaque dossier dans src/app/ devient une URL :

src/app/analytique/page.tsx ➔ dixipolis.vercel.app/analytique

src/app/contenu/page.tsx ➔ dixipolis.vercel.app/contenu

src/app/politicien/[slug]/page.tsx ➔ dixipolis.vercel.app/politicien/macron

Les crochets [slug] créent une page dynamique : le slug change selon le politicien.

⚛

React — l'interface

React, c'est le système de briques. Chaque bout de l'interface est un « composant » réutilisable.

Un composant, c'est une brique d'interface. Par exemple, le Header est un composant, chaque FeatureCard est un composant, le Footer aussi.

L'avantage : tu écris le code UNE fois, et tu le réutilises partout. Si tu changes le Header, il change sur TOUTES les pages.

Les props (propriétés), c'est les paramètres qu'on passe à un composant. Comme quand tu commandes au restaurant : « Un burger, SANS oignon, AVEC cheddar ».

Exemple : <FeatureCard title="Agent IA" description="..." /> — ici, title et description sont des props.

🎨

Tailwind — le style

Au lieu d'écrire du CSS dans des fichiers séparés, Tailwind utilise des classes directement dans le HTML. C'est comme écrire « gros, bleu, centré » sur chaque élément.

{"// Au lieu d'écrire un fichier CSS séparé :"}
<div className="text-lg font-bold text-blue-600 mb-4">
  Mon titre
</div>

{"// text-lg = taille grande"}
{"// font-bold = gras"}
{"// text-blue-600 = couleur bleue"}
{"// mb-4 = marge en bas"}
💡
Astuce : sur Dixipolis, on utilise des variables CSS plutôt que des couleurs Tailwind directes. Exemple : text-[var(--color-primary)] au lieu de text-blue-600. Ça permet de changer toute la palette en un seul endroit (globals.css).
🔐

TypeScript — le filet de sécurité

TypeScript, c'est du JavaScript avec un correcteur orthographique intégré. Il vérifie que tu ne fais pas d'erreurs avant même que le site ne se lance.

Sans TypeScript, tu pourrais écrire user.naem au lieu de user.name et ne le découvrir qu'en production (quand les visiteurs voient le bug).

Avec TypeScript, l'erreur est détectée avant le déploiement, dans ton éditeur de code. C'est un filet de sécurité permanent.

🚀

Déploiement sur Vercel

Vercel, c'est l'hébergeur de ton site. C'est là que le site « vit » sur Internet. Chaque fois que tu modifies le code, Vercel le remet à jour automatiquement.

1. Tu modifies le code

Avec Claude Code, VS Code, ou directement sur GitHub. Tu fais un git push pour envoyer tes modifications.

2. GitHub Actions vérifie

Le pipeline CI (.github/workflows/ci.yml) vérifie automatiquement : lint (style de code), types (pas d'erreurs TypeScript), build (le site compile).

3. Déploiement automatique

Si tout est OK, le workflow deploy (.github/workflows/deploy.yml) envoie le site sur Vercel avec la commande vercel --prod.

4. Le site est en ligne !

En 2 minutes, la nouvelle version est visible sur dixipolis.vercel.app. Tes visiteurs voient les changements.

✅
Ton URL actuelle : https://dixipolis.vercel.app
🔌

Connecter une API

Aujourd'hui, le site affiche des données fictives (mock data) stockées dans src/lib/constants.ts. Pour afficher de vraies données, il faut connecter une API.

Une API, c'est un serveur qui répond à des questions. Tu lui demandes « Donne-moi la liste des politiciens », il te répond avec les données au format JSON.

C'est comme un restaurant : tu passes commande (la requête), la cuisine prépare (le serveur), et on te sert le plat (la réponse).

Étape 1 : Mettre l'URL de l'API dans les variables d'environnement (.env.local).

Étape 2 : Remplacer les données mock par un appel fetch dans les composants.

Étape 3 : Tester localement, puis déployer.

Exemple concret : remplacer les données mock

// src/app/analytique/page.tsx — AVANT
import { MOCK_STATS } from "@/lib/constants";

export default function AnalytiquePage() {
  return <StatsOverview stats={MOCK_STATS} />;
}
// src/app/analytique/page.tsx — APRÈS
export default async function AnalytiquePage() {
  const res = await fetch('https://api.dixipolis.fr/stats');
  const stats = await res.json();
  return <StatsOverview stats={stats} />;
}
⚠
Important : ne mets JAMAIS les clés API directement dans le code ! Utilise toujours les variables d'environnement (.env.local). Voir la section Variables d'environnement.
💾

Base de données (Supabase)

Quand l'API backend sera prête, elle stockera ses données dans Supabase — une base PostgreSQL hébergée dans le cloud, avec une interface visuelle simple.

📊

Interface visuelle

Supabase a un « panneau de contrôle » web où tu peux voir tes données en tableau, comme Excel.

🔐

Sécurisé

Authentification intégrée, accès contrôlé par clés API. Rien n'est accessible sans autorisation.

🚀

Gratuit pour démarrer

Plan gratuit très généreux pour le développement. Passage à l'échelle facile ensuite.

🔑

Variables d'environnement

Les variables d'environnement, c'est le coffre-fort de ton application. C'est là que tu mets les clés API, URLs de base de données, tokens secrets.

# Ce fichier n'est JAMAIS envoyé sur GitHub (dans .gitignore)

NEXT_PUBLIC_SITE_URL=https://dixipolis.vercel.app
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGc...
OPENAI_API_KEY=sk-...

En local : dans le fichier .env.local à la racine du projet.

Sur Vercel : dans Settings > Environment Variables de ton projet Vercel.

Sur GitHub (pour le CI/CD) : dans Settings > Secrets du repo GitHub. Actuellement, 3 secrets sont configurés : VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.

🔒
Règle d'or : les variables qui commencent par NEXT_PUBLIC_ sont visibles côté client (navigateur). Les autres sont secrètes (côté serveur seulement). Ne mets JAMAIS une clé API secrète avec le préfixe NEXT_PUBLIC_.
🔄

CI/CD — GitHub Actions

Le CI/CD, c'est ton assistant automatique. À chaque modification du code, il vérifie que tout est OK et déploie le site sans que tu fasses quoi que ce soit.

✅

ci.yml — Vérification

Se déclenche à chaque push. Vérifie le lint (style de code), les types TypeScript, et que le site compile correctement.

Automatique
🚀

deploy.yml — Déploiement

Après la vérification, envoie le site compilé sur Vercel en production. Tout est en ligne en ~2 minutes.

Automatique
📄

Ajouter une nouvelle page

Tu veux créer la page /mon-truc ? Voici la recette en 3 étapes.

1. Créer le dossier

Crée src/app/mon-truc/ (le nom du dossier = l'URL).

2. Créer page.tsx

Crée src/app/mon-truc/page.tsx avec un composant qui exporte par défaut.

3. C'est fini !

Next.js détecte automatiquement le fichier. La page est accessible à /mon-truc.

import PageWrapper from "@/components/layout/PageWrapper";

export const metadata = {
  title: "Mon Truc | Dixipolis",
};

export default function MonTrucPage() {
  return (
    <PageWrapper>
      <h1>Ma nouvelle page</h1>
      <p>Contenu ici...</p>
    </PageWrapper>
  );
}
✏

Modifier un texte

Pour changer un texte sur le site, il suffit de trouver le bon fichier et de modifier la chaîne de caractères.

Méthode 1 : le nom du dossier = l'URL. Tu veux modifier /analytique ? Ouvre src/app/analytique/page.tsx.

Méthode 2 : utilise la recherche dans ton éditeur (Ctrl+Shift+F) pour trouver le texte exact.

Méthode 3 : demande à Claude Code ! Il connaît tous les fichiers.

💡
Attention aux accents : dans le code JSX, les accents français s'écrivent en entités HTML : &eacute; = é, &agrave; = à, &ccedil; = ç. Dans le JavaScript pur (variables), utilise les caractères Unicode directement : \u00e9.
🧩

Ajouter un composant

Les composants vivent dans src/components/. Organise-les par catégorie (home, layout, contenu, etc.).

{"// Composant serveur par défaut (pas de \"use client\")"}

export default function MonWidget() {
  return (
    <section className="card p-6">
      <h3>Mon widget</h3>
      <p>Contenu ici</p>
    </section>
  );
}
💡
Ajoute "use client" en tout première ligne UNIQUEMENT si ton composant a besoin d'interactivité : useState, useEffect, onClick, formulaires...
🌐

Domaine personnalisé

Pour passer de dixipolis.vercel.app à dixipolis.fr, il faut acheter un nom de domaine et le connecter à Vercel.

1. Acheter le domaine

Sur un registrar (OVH, Gandi, Namecheap...). Coût : ~10-15€/an pour un .fr.

2. Configurer sur Vercel

Dans le dashboard Vercel > Settings > Domains, ajoute ton domaine. Vercel te donne les enregistrements DNS à configurer.

3. Configurer le DNS

Chez ton registrar, ajoute les enregistrements CNAME ou A que Vercel t'a donnés. Propagation en 1-24h.

4. HTTPS automatique

Vercel gère automatiquement le certificat SSL. Ton site est sécurisé (https://) sans rien faire.

❓

Questions fréquentes

Lis le message d'erreur ! Il indique le fichier et la ligne problématique. Les erreurs les plus courantes :

• Import manquant : tu utilises un composant sans l'importer en haut du fichier.

• Erreur de type : tu passes une chaîne de caractères là où un nombre est attendu.

• Variable inutilisée : tu as importé quelque chose que tu n'utilises pas. Supprime l'import.

En cas de doute, demande à Claude Code : il lit l'erreur et la corrige automatiquement.

Ouvre un terminal dans le dossier du projet et tape : npm run dev

Le site sera accessible sur http://localhost:3000. Chaque modification du code est visible instantanément (hot reload).

Dans le terminal : npm install nom-du-package

Ça l'ajoute dans package.json et le télécharge dans node_modules/. Tu peux ensuite l'importer dans ton code.

Toutes les couleurs sont définies dans src/app/globals.css dans la section :root.

Change --color-primary: #2563eb par ta couleur préférée, et TOUT le site changera (boutons, liens, badges, etc.).

Le site a déjà des pages /connexion et /inscription avec les formulaires. Il manque le backend.

Solution recommandée : Supabase Auth. Il gère email/mot de passe, OAuth (Google, GitHub), et les sessions. Gratuit pour les petits projets.

Les fichiers à modifier : src/app/connexion/page.tsx et src/app/inscription/page.tsx pour connecter les formulaires à Supabase Auth.

Vercel Hobby (actuel) : gratuit. Suffisant pour le développement et les premiers utilisateurs.

Vercel Pro : 20$/mois. Nécessaire si tu as plus de 100 GB de bande passante ou besoin de fonctionnalités avancées.

Supabase Free : 500 MB de stockage, 2 GB de bande passante. Largement suffisant pour démarrer.