La carte de Next.js

Tu sais faire des composants, gérer de l'état, parler à un serveur avec fetch. Il te manque tout ce qu'il y a autour : le routage, le serveur, le build, le référencement — le trou exact que Next.js vient boucher. Avant de plonger dans ses mécanismes, qui auront chacun leur module, on dessine la carte : ce qu'il y a dans un projet, où ça vit, à quoi ça sert. Une carte ne te dit pas comment marcher ; elle t'empêche de te perdre.

Pourquoi un framework par-dessus React ?

Le point de départ, c'est de voir à quel point React est petit. Il ne fait qu'une chose : décrire une interface en fonction d'un état — le modèle que tu connais depuis le module sur le modèle de React, dans le guide Halterofit. Il ne dit rien sur : quelle URL affiche quel écran ; comment transformer trente fichiers TypeScript en un paquet que le navigateur sait charger ; comment fabriquer du HTML sur un serveur pour que Google et les réseaux sociaux voient autre chose qu'une page vide ; comment mettre en cache une réponse, redimensionner une image, gérer les variables d'environnement. Aucune de ces questions n'a de réponse dans React, et elles sont pourtant toutes obligatoires dès qu'on met un vrai site en ligne.

Chaque équipe assemblait donc sa propre tour de briques : un bundler (Webpack, puis Vite), un routeur tiers (React Router) dont la configuration se maintient à la main, un serveur de rendu maison pour le SEO — la brique la plus douloureuse, avec deux points d'entrée à garder synchronisés —, une bibliothèque de data fetching et de cache (React Query, SWR), une gestion des métadonnées (titre, Open Graph), un découpage du code réglé à la main pour ne pas envoyer 2 Mo de JavaScript d'un coup, plus les images, les polices, les variables d'environnement et le déploiement. Le vrai coût n'est pas d'écrire une brique : c'est de garantir que les huit s'entendent entre elles, et de continuer à le garantir pendant trois ans de mises à jour.

Un framework, c'est la réponse à ce coût. Next.js prend toutes ces décisions à ta place, les fait tenir ensemble, et te livre l'ensemble déjà câblé : le routage, le bundler (c'est Turbopack, désormais le bundler par défaut), le rendu serveur, le cache, l'optimisation d'images. Tu échanges de la liberté contre de la convention — et la convention, quand elle est bonne, est un accélérateur monumental : tu ne passes plus tes journées à assembler, tu les passes à écrire des fonctionnalités.

Les deux routeurs, et pourquoi on n'apprend que l'App Router

Voici le premier piège de vocabulaire, et il est de taille parce qu'il pollue à peu près tous les tutoriels que tu trouveras en ligne. Next.js a eu deux systèmes de routage successifs, qui coexistent encore dans le même produit. Le Pages Router est le système historique : toujours supporté, il fait tourner des milliers d'applications en production, mais c'est l'ancien monde — tout y est composant client, rendu une fois sur le serveur puis « réhydraté » dans le navigateur. L'App Router est le système actuel : la structure des dossiers y décrit toute la navigation (layouts imbriqués, états de chargement, erreurs), et il est bâti sur les Server Components — par défaut un composant s'exécute sur le serveur et n'envoie jamais son code au navigateur, changement de modèle mental assez profond pour mériter son propre module (Server et Client Components). Ce guide n'enseigne que l'App Router ; de l'ancien monde, tu dois seulement savoir le reconnaître, sinon tu perdras une demi-heure devant un vieux tutoriel ou le dépôt d'un test technique.

Le test le plus rapide devant un dépôt inconnu : y a-t-il un dossier app/ ou un dossier pages/ à la racine (ou dans src/) ? Puis cherche la chaîne getServerSideProps : si elle apparaît, tu es dans l'ancien monde ; si tu vois des layout.tsx partout, dans le nouveau. Un projet peut légitimement contenir les deux pendant une migration progressive — Next.js l'autorise, une route à la fois. Ce changement n'était pas un caprice de version : dans le Pages Router, les données se chargeaient au niveau de la page entière, jamais au niveau du composant qui en avait besoin. Les Server Components suppriment cette contrainte — le module Rendu & data fetching y revient.

// pages/rendez-vous/[service].tsx — l'ANCIEN monde, recopié tel quel
export async function getServerSideProps({ params }) {
  const slots = await findSlots(params.service);
  return { props: { slots } };
}

export default function Page({ slots }) {
  return <ul>{slots.map((s) => <li key={s.id}>{s.heure}</li>)}</ul>;
}

L'anatomie d'un projet Next.js

À quoi ressemble le dossier d'un projet fraîchement créé ? Rassurant : il y a très peu de choses, Next.js n'exige presque aucune configuration. Prends le temps d'associer chaque entrée à son rôle, c'est ce que tu chercheras des yeux dans chaque projet que tu ouvriras.

mon-projet/
├── app/                  ← LE cœur : chaque dossier ici devient un segment d'URL
├── public/               ← fichiers servis tels quels : /logo.svg, /robots.txt, favicon…
├── next.config.js        ← configuration du framework (images distantes, redirections…)
├── proxy.ts              ← code exécuté AVANT la route (redirections, en-têtes, auth légère)
├── .env.local            ← secrets et réglages de TA machine — jamais commité
├── eslint.config.mjs     ← règles de qualité de code (ESLint, config « à plat »)
├── tsconfig.json         ← réglages TypeScript, dont l'alias d'import « @/ »
├── next-env.d.ts         ← types générés par Next.js — on ne le modifie JAMAIS à la main
├── package.json          ← dépendances + les scripts dev / build / start
└── node_modules/         ← les dépendances installées (jamais commité)

Un projet Next.js minimal. Certains glissent app/ (et proxy.ts) dans un dossier src/ : option officielle, purement cosmétique, ne te laisse pas surprendre.

Détaillons les entrées les moins évidentes.

public/ contient les fichiers statiques, servis tels quels sans passer par le build : public/logo.svg est accessible à l'adresse /logo.svg — la racine du site correspond à la racine de public/, pas à /public/…. C'est là que vont le favicon, les images de marque, un robots.txt. Corollaire à ne jamais oublier : tout ce que tu y mets est téléchargeable par n'importe qui — ce n'est pas un endroit pour un fichier « interne ».

proxy.ts est le plus récent de la liste, et son nom a changé : c'est le successeur de ce que l'écosystème appelait middleware.ts — si tu croises ce nom-là dans un article, c'est l'ancienne appellation de la même case. La fonction qu'il exporte s'exécute avant que Next.js ne décide quelle route rendre, sur chaque requête qui correspond à son matcher (le filtre d'URL qu'on lui déclare) : redirections, réécritures d'URL, pose d'un en-tête ou d'un cookie. L'équipe Next.js insiste sur un point — c'est un outil de dernier recours, pas l'endroit où mettre ta logique métier ni ta seule vérification d'autorisation, laquelle doit aussi vivre au plus près des données.

next.config.js, enfin, est court mais dense en indices : les domaines d'images autorisés révèlent d'où viennent les médias, les redirections révèlent l'histoire du site (une page qui a bougé, une ancienne URL qu'on honore), les options expérimentales révèlent le niveau de risque que l'équipe accepte. C'est par lui, et par proxy.ts s'il existe, qu'on entre dans un dépôt inconnu ; la méthode complète est dans le module Lire et critiquer du code frontend.

Le dossier app/ : les dossiers font les URL, les fichiers font le comportement

Voici la règle centrale, et si tu ne devais retenir qu'une phrase de ce module, ce serait celle-ci : dans app/, les DOSSIERS définissent les URL, et les NOMS DE FICHIERS définissent le comportement. Deux axes indépendants, qu'il faut arriver à voir séparément.

Premier axe, les dossiers. Chaque dossier imbriqué sous app/ ajoute un segment à l'URL : app/rendez-vous/confirmation/ correspond à /rendez-vous/confirmation. Tu retrouves là exactement le routage par fichiers d'Expo Router — c'est Next.js qui a popularisé l'idée côté web, et Expo Router qui l'a portée sur mobile. Deuxième axe, les fichiers : un dossier tout seul ne produit rien, ce sont des fichiers aux noms réservés qui lui donnent un comportement. Voici les neuf que tu dois savoir reconnaître — l'alphabet du framework.

Ces noms s'écrivent avec l'extension de ton choix : .tsx pour tout ce qui rend du JSX, .ts pour un route, qui ne rend que des données.

La conséquence la plus utile : la colocalisation

La conséquence pratique est énorme. Puisqu'un segment n'est public que s'il contient un page ou un route, tous les autres fichiers que tu poses dans app/ sont… simplement des fichiers : personne ne peut « visiter » app/rendez-vous/creneaux.ts, c'est un module que ton code importe, point.

Cela autorise la colocalisation : ranger composants, utilitaires, tests et types à côté de la page qui les utilise plutôt que dans un lointain components/ global. Confort de lecture considérable — tu ouvres un dossier de fonctionnalité et tu vois tout ce qui la concerne ; tu supprimes la fonctionnalité, tu supprimes un dossier, et rien ne traîne.

Deux conventions complètent le tableau — le module Routing les détaille :

• Les groupes (nom) — un dossier entre parenthèses organise sans apparaître dans l'URL : app/(marketing)/tarifs/page.tsx répond à /tarifs, pas à /marketing/tarifs. Intérêt : un layout commun sans polluer les adresses.
• Les dossiers privés _nom — le tiret bas exclut totalement le dossier et tous ses enfants du routage. app/rendez-vous/_components/ ne pourra jamais, même par accident, devenir une URL.

Pour les URL variables, la syntaxe reprend celle que tu connais : [slug] capture un segment ; [...slug] (« catch-all ») en capture plusieurs d'un coup, donc /a/b/c ; [[...slug]] accepte en plus aucun segment, ce qui lui fait couvrir le chemin parent. Restent les slots @nom (routes parallèles : plusieurs pages côte à côte dans un même layout) et l'interception (.), (..), (...), qui ouvre une route en modale par-dessus la page courante tout en changeant l'URL. Tout cela est détaillé dans le module Routing : segments, layouts, navigation, dont la table de conversion Expo Router ↔ App Router transpose ligne à ligne les conventions que tu connais déjà.

app/
├── layout.tsx
├── page.tsx
├── (marketing)/
│   ├── layout.tsx
│   ├── a-propos/page.tsx
│   └── tarifs/page.tsx
├── rendez-vous/
│   ├── page.tsx
│   ├── slots.ts
│   ├── _components/CarteCreneau.tsx
│   └── [service]/
│       ├── page.tsx
│       └── loading.tsx
├── admin/
│   └── stats.tsx
└── api/
    └── services/route.ts

La page minimale et le layout racine

Le plus petit site Next.js qui fonctionne tient en deux fichiers, et ces deux fichiers sont la formule de ce module : tout le reste du framework n'en est qu'une variation.

Le premier est le layout racine, app/layout.tsx : obligatoire — le seul fichier dont Next.js exige l'existence — avec une particularité qui surprend toujours au début, c'est lui qui écrit les balises <html> et <body>. Il n'y a pas d'index.html dans un projet Next.js : le document n'existe nulle part sur le disque, il est produit par ce composant, à chaque requête ou au moment du build. Quant à la prop children qu'il reçoit, c'est le contenu du segment enfant — la page, ou un layout plus profond. Tu reconnais le patron de composition que tu utilises depuis toujours en React : un composant enveloppe qui rend {children} au milieu de sa propre structure. Ici, la « structure » se trouve juste être le squelette du document.

// app/layout.tsx — OBLIGATOIRE, une seule fois, à la racine.
// C'est lui qui écrit <html> et <body> : il n'y a pas d'index.html.
export default function RootLayout({
  children,                                  // ← le segment enfant : la page, ou un layout plus profond
}: { children: React.ReactNode }) {
  return (
    <html lang="fr">
      <body>{children}</body>
    </html>
  );
}

// app/page.tsx — la page de l'URL « / ». Export DEFAULT obligatoire.
export default function Page() {
  return <h1>Bienvenue chez RendezVous</h1>;
}

Deux détails de cette formule, sources d'erreurs très fréquentes chez les débutants. L'export doit être default : Next.js va chercher l'export par défaut de page.tsx pour savoir quel composant rendre, et un export function Page() nommé, sans default, produit une erreur au build. Le nom de la fonction, lui, n'a aucune importance. Et le layout racine ne se remonte pas : comme il contient <html> et <body>, tout ce que tu y mets — barre de navigation, pied de page, police, thème — s'applique à absolument toutes les pages du site, et les layouts plus profonds (app/(marketing)/layout.tsx) ne redéclarent pas ces balises : ils s'insèrent simplement à l'intérieur, comme des poupées russes.

Et regarde ce que ce layout racine produit, une fois rendu : <html lang="fr">, un <body>, du contenu dedans. C'est La page web minimale du module Du mobile au web : lire ce guide, à peine déguisée — le squelette n'a pas disparu, il a changé de forme : il s'écrit maintenant en JSX, dans un composant React, au lieu d'un fichier index.html. Le <head> non plus n'a pas disparu ; simplement, tu ne le tapes plus toi-même : Next.js l'assemble à partir de l'objet metadata que tu exportes.

C'est aussi pour cela qu'ouvrir app/layout.tsx est le premier geste devant un dépôt inconnu : en trente secondes tu y vois la langue, les polices, le thème, l'en-tête et le pied de page, et surtout les fournisseurs (providers) qui enveloppent l'application — un thème, une session, un client de données. Ces fournisseurs te disent quelles grandes technologies sont en jeu avant même que tu aies lu le package.json.

// app/layout.tsx
import { EnTete } from '@/components/EnTete';
import { PiedDePage } from '@/components/PiedDePage';

export default function RootLayout({
  children,
}: { children: React.ReactNode }) {
  return (
    <html lang="fr">
      <body>
        <EnTete />
        <PiedDePage />
      </body>
    </html>
  );
}

Le squelette de RendezVous

Posons l'application qui va nous accompagner tout au long de ce guide. RendezVous est un site de prise de rendez-vous pour une clinique : on présente les services offerts (physiothérapie, dentiste, massothérapie…), on en choisit un, on voit les créneaux libres, on réserve. C'est petit, mais assez réel pour rencontrer tous les sujets du guide — données à charger, formulaire à valider, API à appeler, états de chargement et d'erreur, référencement à soigner. À ce stade, ne cherche pas à comprendre comment chaque pièce fonctionne : il s'agit seulement de rendre ce dessin familier, pour que les modules suivants aient un territoire où se poser.

app/
├── layout.tsx                  ← <html>/<body>, en-tête et pied de page du site entier
├── page.tsx                    → /                 (accueil : la liste des services)
├── loading.tsx                 ← squelette affiché pendant le chargement de l'accueil
├── not-found.tsx               ← la page 404 du site
│
├── (legal)/                    ← groupe : n'apparaît PAS dans les URL
│   ├── layout.tsx              ← une mise en page « document » commune aux deux pages
│   ├── confidentialite/page.tsx → /confidentialite
│   └── conditions/page.tsx      → /conditions
│
├── rendez-vous/
│   ├── page.tsx                → /rendez-vous      (choisir un service)
│   └── [service]/              ← segment dynamique
│       ├── page.tsx            → /rendez-vous/physio, /rendez-vous/dentiste…
│       ├── loading.tsx         ← attente pendant le chargement des créneaux
│       ├── error.tsx           ← filet si le chargement des créneaux échoue
│       └── _components/        ← dossier PRIVÉ : jamais une URL
│           ├── SlotGrid.tsx
│           └── BookingForm.tsx
│
└── api/
    └── services/route.ts       → /api/services     (répond du JSON, pas du HTML)

components/                     ← composants réutilisés PARTOUT (Button, Field, Badge…)
lib/                            ← logique sans interface : accès aux données, validation, dates
public/                         ← logo.svg, favicon, images des services

Lis cette carte avec la règle du module : les dossiers font les URL (colonne de droite), les noms de fichiers font le comportement. (legal) et _components ne produisent aucune adresse.

1. app/equipe/page.tsx
2. app/equipe/EquipeGrille.tsx

Les scripts et le cycle de vie du projet

Un projet Next.js s'utilise avec trois commandes, déclarées dans les scripts du package.json. Elles correspondent à trois moments distincts de la vie du code, et confondre ces moments est une source classique de confusion.

Arrêtons-nous sur build, parce que le mot est trompeur quand on vient du mobile. Chez Expo, « build » veut dire compiler : produire un binaire installable. Ici, il recouvre deux opérations. La première est bien la compilation — TypeScript et JSX en JavaScript que les navigateurs comprennent, découpage en morceaux chargés à la demande, minification, feuilles de style. La seconde est le pré-rendu, la vraie particularité d'un framework web : pour chaque page qui n'a pas besoin d'informations propres à un visiteur, Next.js exécute ton composant tout de suite, pendant le build, et enregistre le HTML sur le disque. À l'exécution il n'y a plus rien à calculer, d'où des pages quasi instantanées et parfaitement lisibles par les moteurs de recherche.

D'où le fait qu'un build échoue parfois sur une erreur qui, en apparence, ne se produit « qu'à l'exécution » : cette exécution a lieu maintenant. Quelles pages sont pré-rendues et selon quels critères, c'est le sujet du module Rendu & data fetching.

Les variables d'environnement, et la ligne rouge du secret

Un site a besoin de valeurs qui changent selon l'endroit où il tourne : adresse de la base de données, clé d'API, URL publique du site. Elles n'ont rien à faire dans le code — on les met dans un .env.local, qui reste sur ta machine et n'est jamais commité (le .gitignore par défaut s'en charge) ; en production, l'hébergeur offre son propre écran pour les saisir.

# .env.local — jamais commité, jamais partagé

# Reste sur le SERVEUR : jamais envoyée au navigateur.
CLE_API_CLINIQUE=sk_live_9f3b2c...

# Le préfixe NEXT_PUBLIC_ = « recopie-moi dans le JavaScript du navigateur ».
# À réserver aux valeurs QUE TOUT LE MONDE PEUT VOIR.
NEXT_PUBLIC_URL_SITE=https://rendezvous.example.com

Deux variables, deux destins radicalement différents — et la seule chose qui les sépare est un préfixe de douze caractères.

La règle est simple au point d'être facile à sous-estimer. Par défaut, une variable d'environnement reste sur le serveur : ton code serveur lit process.env.CLE_API_CLINIQUE, mais cette chaîne n'est écrite nulle part dans ce qui part vers le navigateur. C'est le comportement sûr, et c'est celui par défaut.

Le préfixe NEXT_PUBLIC_ renverse ce comportement. Il dit à Next.js : « recopie littéralement cette valeur dans le JavaScript envoyé au navigateur ». Le mot important est littéralement — au build, chaque occurrence de process.env.NEXT_PUBLIC_URL_SITE est remplacée par la chaîne elle-même dans le fichier livré, que n'importe qui peut lire dans les outils de développement de son navigateur. Ce n'est pas une faille, c'est le but déclaré du préfixe ; la faille, c'est de le mettre devant quelque chose qui devait rester secret. Conséquence souvent découverte à la dure : puisque la substitution a lieu au build, changer une variable NEXT_PUBLIC_ chez ton hébergeur ne suffit pas — il faut reconstruire. Les variables serveur, elles, sont lues à l'exécution et prennent effet au redémarrage.

# Variables d'environnement de production — modifiées il y a deux minutes
CLE_API_CLINIQUE=sk_live_NOUVELLE
NEXT_PUBLIC_URL_SITE=https://rendezvous.ca

Ce que Next.js apporte encore, en survol

Le routage et le rendu sont le cœur du framework, mais Next.js embarque d'autres outils, chacun réglant un problème classique du web. On ne fait ici que les nommer, pour que tu saches qu'ils existent et où les retrouver.

• Les images (next/image). Un composant <Image /> qui remplace <img> et automatise ce que personne ne fait à la main : format moderne, redimensionnement selon l'écran, chargement paresseux hors de vue, et place réservée d'avance pour que la page ne « saute » pas quand l'image arrive — ce dernier point est mesuré par Google et compte dans le référencement.
• Les polices (next/font). Téléchargées et servies depuis ton propre domaine plutôt que depuis un service tiers : plus rapide, meilleur pour la vie privée, et sans clignotement de texte au chargement.
• Les métadonnées et le SEO. Titre de l'onglet, description, image de partage sur les réseaux sociaux : tout se déclare en exportant un objet metadata depuis un layout ou une page, et Next.js génère les balises dans le vrai HTML, celui que les robots lisent sans exécuter de JavaScript. Un site React classique leur renvoie une page vide ; un site Next.js, du contenu.
• Le streaming — le serveur envoie le HTML par morceaux au lieu d'attendre que toute la page soit prête (fichiers loading, frontières Suspense) — et le cache, la partie la plus subtile du framework : Next.js peut cacher le résultat d'un fetch, le HTML d'une page, la navigation côté client, avec des règles précises pour le demander et l'invalider. Sujet du module Rendu & data fetching.

// app/rendez-vous/[service]/page.tsx
export default async function Page({
  params,                                   // ← une PROMESSE, pas un objet simple
}: { params: Promise<{ service: string }> }) {
  const { service } = await params;         // ← d'où le await, et l'async ci-dessus
  return <h1>Créneaux pour {service}</h1>;
}

// app/rendez-vous/[service]/page.tsx
'use client';
import { useEffect } from 'react';

export default function Page() {
  useEffect(() => {
    document.title = 'Physiothérapie — RendezVous';
  }, []);

  return <h1>Physiothérapie</h1>;
}