Route Handlers & Server Actions

Jusqu'ici, dans toute ta vie de développeur, tu as consommé des API : tu envoyais des requêtes à Supabase et tu affichais ce qui revenait. Ce module est celui où tu passes de l'autre côté du comptoir. Next.js te donne deux façons d'écrire du code qui s'exécute sur le serveur, dans le même projet que tes composants : les Route Handlers, qui exposent une vraie URL d'API, et les Server Actions, qui branchent une fonction serveur directement sur un formulaire. Deux outils, deux usages, et une question d'entrevue quasi garantie en 2026 : « comment choisis-tu entre les deux ? »

Ton frontend a un serveur

Mesure la bascule mentale, elle est plus grande qu'elle n'en a l'air. Dans ton app mobile Halterofit, l'architecture est nette : d'un côté ton code, sur le téléphone de l'utilisateur ; de l'autre Supabase, un serveur que tu n'as pas écrit et à qui tu parles en HTTP. La frontière est physique et organisationnelle — le « backend » est le produit de quelqu'un d'autre, tu es un client au sens strict.

Une application Next.js casse cette séparation : elle est fullstack par construction. Une partie de ton code s'exécute dans le navigateur, une autre sur un serveur Node, et les deux vivent dans le même dossier, le même dépôt Git, le même package.json. Tu n'as pas deux projets qui se parlent par-dessus un réseau : tu as un projet qui a deux moitiés. Le réseau n'a pas disparu, mais il ne sépare plus deux équipes, il sépare deux parties de ton fichier.

Ce module ajoute la dernière pièce. Le module sur le rendu et le data fetching t'a appris à lire depuis le serveur ; mais une application réelle doit aussi écrire : créer un rendez-vous, annuler une réservation, mettre à jour un profil. L'écriture — la mutation, dans le vocabulaire du métier — pose des questions que la lecture ne pose pas. Qui a le droit ? Les données envoyées sont-elles valides ? Que faire si l'opération échoue à mi-chemin ? Comment rafraîchir l'écran après coup ? Next.js répond avec deux mécanismes.

Pourquoi ça compte pour un stagiaire frontend ? Parce que la frontière du métier a bougé : une offre « développeur frontend Next.js » suppose presque toujours que tu saches écrire une route d'API simple, valider ce qui arrive et répondre avec le bon statut. Il ne s'agit pas de devenir architecte de bases de données, mais d'écrire les trente lignes de serveur dont ta page a besoin sans mendier un endpoint à l'équipe backend. En entrevue, c'est exactement la différence entre « je fais des composants » et « je livre des fonctionnalités ».

Le Route Handler : une URL, un fichier, des fonctions nommées

Commençons par le mécanisme le plus proche de ce que tu connais déjà, parce qu'il ne fait que te placer de l'autre côté de la conversation du module HTTP & fetch. Un Route Handler, c'est un fichier nommé route.ts posé dans un segment du dossier app/. Le chemin du dossier devient l'URL ; le fichier contient les fonctions qui répondent.

app/
├─ page.tsx                          → la page   /
├─ reserver/
│  └─ page.tsx                       → la page   /reserver
└─ api/
   ├─ services/
   │  └─ route.ts                    → l'API     /api/services
   └─ appointments/
      ├─ route.ts                    → l'API     /api/appointments
      └─ [id]/
         └─ route.ts                 → l'API     /api/appointments/42

Même convention de routage par dossiers que dans le module sur le routing — un page.tsx produit une page HTML, un route.ts produit une réponse HTTP brute. Le dossier api/ n'a rien de magique, c'est une simple convention de lisibilité.

Le cœur de la convention vaut d'être savouré : le nom de la fonction exportée EST la méthode HTTP. Tu exportes GET, elle répond aux requêtes GET ; tu exportes POST, elle répond aux POST. Les noms reconnus sont les verbes du module HTTP & fetch : GET, POST, PUT, PATCH, DELETE, plus HEAD et OPTIONS. Aucun routeur à configurer, aucun switch (method) : le tableau de routes devient littéralement une liste d'export.

import { listerServices } from '@/lib/services';

// Le NOM de la fonction exportée est le verbe HTTP auquel elle répond.
// Ici : GET /api/services
export async function GET() {
  const services = await listerServices();   // requête base de données, côté serveur

  // Response.json() fabrique une réponse : il sérialise l'objet en JSON
  // ET pose l'en-tête Content-Type: application/json pour toi.
  // Sans second argument, le statut est 200.
  return Response.json(services);
}

Six lignes utiles, et l'URL /api/services existe. C'est exactement la réponse 200 OK que tu décodais dans le module HTTP & fetch — sauf que cette fois, c'est toi qui l'écris.

Regarde les deux types en jeu, familiers et c'est volontaire : un Route Handler reçoit une Request et renvoie une Response — les objets standard de la plateforme web, les mêmes que ceux que fetch manipule côté navigateur. Quand tu écrivais const res = await fetch(...) puis res.status, tu tenais un objet Response ; ici tu en fabriques un. Next.js n'a pas inventé un format maison, ce que tu apprends ici te resservira dans un Cloudflare Worker, une Edge Function Supabase ou un serveur Deno.

Le statut se choisit avec le second argument, et c'est ta responsabilité éditoriale : tu décides désormais du verdict en trois chiffres. Rappelle-toi le panthéon du module HTTP & fetch — 200 pour une lecture réussie, 201 pour une création, 400 pour une requête mal formée, 404 pour un introuvable, 409 pour un conflit — car ce tableau n'est plus une grille de lecture, c'est une grille d'écriture.

// Le second argument porte le statut et, si besoin, des en-têtes.
return Response.json({ error: 'not_found' }, { status: 404 });

// Response.json est un raccourci. L'équivalent long, utile quand
// tu renvoies autre chose que du JSON (du texte, un fichier, rien) :
return new Response('Créneau indisponible', { status: 409 });

// Une réponse sans corps du tout (ex. après un DELETE réussi) : 204 No Content.
return new Response(null, { status: 204 });

Response.json(data, { status }) couvre 90 % des cas. Next.js fournit aussi NextResponse, une sous-classe qui ajoute quelques commodités (cookies, redirections) ; commence par la version standard, tu ajouteras NextResponse quand un besoin précis l'exigera.

// app/api/services/route.ts
import { listerServices } from '@/lib/services';

export async function handler(request: Request) {
  const services = await listerServices();
  return Response.json(services);
}

POST, ou les quatre gestes d'une mutation

Une route de lecture est facile. Une route d'écriture, c'est là que le métier commence, parce qu'elle doit se méfier. Le corps qui arrive vient du monde extérieur : il peut être incomplet, mal typé, hostile. Et la réponse doit dire la vérité — pas juste « 200, ça s'est bien passé » par réflexe.

Toute mutation honnête se déroule en quatre gestes, toujours dans le même ordre : lire le corps, valider son contenu, agir (c'est-à-dire faire le vrai travail), répondre avec le bon statut. Cet ordre n'est pas décoratif : valider avant de lire est impossible, agir avant de valider est un bug de sécurité, et répondre sans distinguer les cas est ce qui rend une API inutilisable pour celui qui la consomme.

Premier geste : lire. Le corps s'obtient avec await request.json() — la même méthode que res.json() côté client, et pour la même raison : le corps arrive en flux, donc c'est une Promesse. La symétrie est complète, celui qui envoie fait JSON.stringify, celui qui reçoit fait request.json(). Deuxième geste : valider, et tu as déjà l'outil — le validateur pur du module Formulaires 2, une fonction qui prend les données, ne touche à rien et rend un objet d'erreurs par champ. Une fonction pure ignore si elle tourne dans un navigateur ou sur un serveur ; tu appelles donc la même fonction, importée du même fichier, dans ton handler. Ce n'est pas un hasard heureux, c'est précisément le bénéfice qu'on cherchait en la gardant pure.

Troisième geste : agir, en déléguant à une fonction métier — la section « Où mettre la logique : le handler traduit, la fonction métier travaille » dira pourquoi c'est un principe et pas un caprice. Quatrième geste : répondre, avec le statut qui décrit honnêtement ce qui vient de se passer. Les quatre gestes assemblés, sur la vraie route de réservation de RendezVous :

import { validerReservation } from '@/lib/validation';
import { creerRendezVous, SlotTakenError } from '@/lib/appointments';

export async function POST(request: Request) {
  // 1. LIRE — request.json() rend une Promesse, comme res.json() côté client.
  const body = await request.json();

  // 2. VALIDER — le validateur PUR de Formulaires 2, réutilisé tel quel ici.
  const errors = validerReservation(body);
  if (Object.keys(errors).length > 0) {
    // 400 : "ta requête est mal formée" — on renvoie le détail par champ,
    // pour que le client puisse afficher l'erreur sous le bon input.
    return Response.json({ errors }, { status: 400 });
  }

  try {
    // 3. AGIR — la fonction métier ne connaît rien à HTTP.
    const rdv = await creerRendezVous(body);
    // 4. RÉPONDRE — 201 Created, avec la ressource créée dans le corps.
    return Response.json(rdv, { status: 201 });
  } catch (err) {
    // Un conflit métier n'est PAS un plantage : c'est un 409 assumé.
    if (err instanceof SlotTakenError) {
      return Response.json(
        { error: 'slot_taken', message: 'Ce créneau vient d\'être réservé.' },
        { status: 409 },
      );
    }
    throw err;   // inconnu : on laisse remonter, Next.js répondra 500 et loguera
  }
}

Relis le corrigé de l'exercice 409 du module HTTP & fetch : tu décodais alors cette réponse depuis le siège du client. Tu viens d'écrire le serveur qui l'émet.

Deux détails méritent qu'on s'y arrête. D'abord, le corps d'erreur du 400 n'est pas une chaîne vague mais un objet structuré par champ : c'est ce qui permet au formulaire d'afficher « la date est obligatoire » sous l'input date plutôt qu'un bandeau rouge générique. Une API qui renvoie { "error": "invalid" } oblige le frontend à deviner ; { "errors": { "date": "..." } } lui donne de quoi travailler.

Ensuite, la distinction entre 409 et 500. Un créneau déjà pris n'est pas un bug : c'est une situation métier normale qui mérite un statut précis et un message lisible. Un plantage inattendu, lui, doit remonter — la maxime « 4xx ta faute, 5xx la mienne » appliquée depuis le siège du conducteur : avaler une exception inconnue pour renvoyer un joli 200 est la façon la plus efficace de rendre un bug indébogable. D'où le throw err final, qui n'est pas de la négligence : Next.js l'attrape, le journalise côté serveur avec sa trace complète (invisible du client) et répond 500. Tu as géré ce que tu comprends, et tu es honnête sur le reste.

export async function POST(request: Request) {
  const body = await request.json();
  const errors = validate(body);
  if (Object.keys(errors).length) return Response.json({ errors }, { status: 400 });
  const created = await creerRendezVous(body);
  return Response.json(created, { status: 201 });
}

export async function POST(request: Request) {
  const body = await request.json();
  try {
    const rdv = await creerRendezVous(body);
    return Response.json({ ok: true, rdv });
  } catch (err) {
    return Response.json({ ok: false, message: 'Erreur' });
  }
}

Paramètres dynamiques et query string

Une API sérieuse a des routes qui parlent d'une ressource : /api/appointments/42. Rien de neuf ici — les segments dynamiques [id], le second argument de contexte et le await params obligatoire (avec le piège du undefined silencieux) sont traités en détail dans le module Routing : segments, layouts, navigation ; la règle est strictement la même pour un Route Handler que pour une page.

import { lireRendezVous, cancelAppointment } from '@/lib/appointments';

// Le contexte : params est une PROMESSE d'objet, pas un objet.
type Contexte = { params: Promise<{ id: string }> };

export async function GET(request: Request, { params }: Contexte) {
  const { id } = await params;              // ⚠️ le await est OBLIGATOIRE

  const rdv = await lireRendezVous(id);
  if (!rdv) return Response.json({ error: 'not_found' }, { status: 404 });

  return Response.json(rdv);
}

// Même fichier, autre verbe : DELETE /api/appointments/42
export async function DELETE(request: Request, { params }: Contexte) {
  const { id } = await params;
  await cancelAppointment(id);
  return new Response(null, { status: 204 });   // 204 : succès, pas de corps
}

Deux verbes, un fichier, une URL. Le nom du dossier [id] devient la clé dans params : renomme le dossier en [appointmentId] et c'est params.appointmentId qu'il faudra lire.

Et la query string — cette partie de l'URL après le ? que tu sais lire depuis le module HTTP & fetch ? Elle n'arrive pas dans params, et c'est normal : elle ne fait pas partie du chemin, elle le précise. Elle vit dans l'URL de la requête, et on la lit avec un outil standard du web, l'objet URL :

export async function GET(request: Request) {
  // request.url est la chaîne complète ; new URL(...) la découpe pour toi.
  const { searchParams } = new URL(request.url);

  // .get() rend une chaîne, ou null si le paramètre est absent.
  const service = searchParams.get('service');        // 'bone-scan' | null
  const jour = searchParams.get('date') ?? aujourdhui();

  // ⚠️ TOUT ce qui vient de l'URL est une CHAÎNE, et vient du client.
  // Un "?limit=abc" ou "?limit=999999" est parfaitement possible :
  // on convertit ET on borne, on ne fait jamais confiance.
  const limite = Math.min(Number(searchParams.get('limit')) || 20, 100);

  const slots = await listerCreneaux({ service, jour, limite });
  return Response.json(slots);
}

searchParams est un URLSearchParams — la même classe que celle disponible dans le navigateur. Encore une fois : API Web standard, pas invention Next.js.

Le commentaire sur limit n'est pas anodin : la query string est du texte fourni par le client, au même titre que le corps d'un POST. Un ?limit=1000000 tapé dans la barre d'adresse est une requête parfaitement valide du point de vue de HTTP — et si ton handler le passe tel quel à la base, tu viens d'offrir un bouton « ralentis mon serveur » à n'importe quel visiteur. Convertir, borner, se méfier : le réflexe de la validation du corps, appliqué à l'URL.

// app/api/appointments/[id]/route.ts
type Contexte = { params: Promise<{ id: string }> };

export async function GET(request: Request, { params }: Contexte) {
  const rdv = await lireRendezVous(params.id);
  if (!rdv) return Response.json({ error: 'not_found' }, { status: 404 });

  return Response.json(rdv);
}

Où mettre la logique : le handler traduit, la fonction métier travaille

Tous les handlers de ce module appellent des fonctions (listerServices, creerRendezVous, cancelAppointment) sans jamais montrer leur contenu. Ce n'est pas de l'esquive pédagogique, c'est la règle d'architecture du module : le handler traduit du HTTP, la fonction métier fait le travail. Le handler est un traducteur de frontière dont la seule compétence est HTTP — lire un corps, extraire des paramètres, choisir un statut, poser des en-têtes ; il ne sait rien du métier des rendez-vous. Inversement, creerRendezVous ne sait rien de HTTP : elle reçoit des données propres, vérifie les règles du domaine, écrit en base, lève une exception métier si le créneau est pris, et ignore jusqu'à l'existence des codes de statut.

Pourquoi séparer, alors que tout tiendrait dans un seul fichier ? Trois raisons, par ordre d'importance croissante.

• La testabilité. Tester une fonction quasi-pure, c'est l'appeler avec des arguments et regarder ce qui sort ; tester un handler, c'est fabriquer une Request, l'invoquer, puis désassembler une Response. Faisable — on le fera dans le module Tester le web — mais chaque règle métier testée à travers HTTP coûte cinq fois plus cher et se casse au moindre changement de format.
• La réutilisation. La même logique « créer un rendez-vous » sera appelée depuis le Route Handler et depuis la Server Action de la section « Les Server Actions : la deuxième voie » : deux points d'entrée, une seule implémentation des règles. Si « pas plus de deux rendez-vous par jour et par patient » vit dans le handler, la Server Action ne l'applique pas — une faille par duplication oubliée.
• La lisibilité en revue. Un handler de quinze lignes se relit d'un coup d'œil : on voit la séquence lire/valider/agir/répondre et on peut juger. Un handler de quarante lignes qui ouvre une transaction, calcule des disponibilités, envoie un email et formate une réponse est un signal d'alarme en revue — non parce que quarante serait un chiffre magique, mais parce qu'à cette longueur il mélange forcément deux niveaux de préoccupation.

app/api/appointments/route.ts   ← 15 lignes : HTTP, rien que HTTP
lib/appointments.ts             ← les règles métier, testables seules
lib/validation.ts               ← les validateurs purs, partagés client/serveur

Trois fichiers, trois responsabilités. Le dossier lib/ n'est pas une convention Next.js imposée — c'est juste le nom que la communauté a adopté pour « le code qui n'est ni une page ni une route ».

Les Server Actions : la deuxième voie

Deuxième mécanisme, et changement de philosophie. Reprends le trajet complet d'une réservation via Route Handler : un onSubmit client intercepte l'envoi, appelle preventDefault(), rassemble l'état des champs, construit un objet, le passe à JSON.stringify, appelle fetch avec la bonne URL et le bon en-tête, vérifie res.ok, parse la réponse, met à jour l'état d'erreur. Ça marche, mais c'est beaucoup de plomberie pour dire « enregistre ça » — et les deux moitiés de ce travail, sérialisation et désérialisation du même JSON, sont dans ton projet, écrites par toi.

Les Server Actions suppriment cette plomberie. Une Server Action est une fonction asynchrone marquée par la directive 'use server', placée soit en tête de fichier (tout le fichier devient un module de Server Actions), soit en tête de la fonction elle-même. Cette directive dit à Next.js : « cette fonction s'exécute uniquement sur le serveur, mais elle peut être référencée depuis le client ». Le compilateur remplace alors, côté client, la fonction par une référence, et fabrique automatiquement l'aller-retour HTTP. Tu écris un appel de fonction ; Next.js écrit la requête.

Voici la Server Action de réservation de RendezVous. Compte les fetch : il n'y en a aucun.

'use server';   // en tête de fichier : tout ce module est un point d'entrée serveur

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
import { validerReservation } from '@/lib/validation';
import { creerRendezVous } from '@/lib/appointments';
import { utilisateurCourant } from '@/lib/auth';

export async function reserver(formData: FormData) {
  // Branchée sur <form action={...}>, l'action reçoit un FormData.
  // Les clés sont les attributs name= des champs : le name redevient VITAL.
  const data = {
    serviceId: String(formData.get('serviceId') ?? ''),
    date: String(formData.get('date') ?? ''),
    heure: String(formData.get('heure') ?? ''),
  };

  const errors = validerReservation(data);
  if (Object.keys(errors).length > 0) return { errors };   // on y revient section « L'état d'une action côté interface »

  // L'authentification se vérifie ICI, dans l'action (voir section « Sécurité, sobrement »).
  const user = await utilisateurCourant();
  if (!user) redirect('/connexion');

  const rdv = await creerRendezVous({ ...data, patientId: user.id });

  revalidatePath('/mes-rendez-vous');   // la liste est périmée : rafraîchis-la
  redirect(`/mes-rendez-vous/${rdv.id}`);
}

Aucune URL, aucun JSON.stringify, aucun res.ok. La requête HTTP existe toujours — ouvre l'onglet Network, tu la verras — mais c'est Next.js qui l'écrit.

Côté page, le branchement tient en un attribut. L'attribut action d'un <form> attend historiquement une URL ; React 19 accepte désormais qu'on lui passe une fonction. Et remarque : cette page est un Server Component — pas de 'use client', pas de useState, pas de gestionnaire d'événement.

import { reserver } from '@/app/actions/reserver';

export default function BookingPage() {
  return (
    <form action={reserver}>
      {/* Chaque name= devient une clé du FormData reçu par l'action. */}
      <input type="hidden" name="serviceId" value="bone-scan" />

      <label htmlFor="date">Date</label>
      <input id="date" name="date" type="date" required />

      <label htmlFor="heure">Heure</label>
      <input id="heure" name="heure" type="time" required />

      <button type="submit">Réserver</button>
    </form>
  );
}

Un formulaire complet et fonctionnel, sans une ligne de JavaScript client. Compare avec la version « contrôlée » du module Formulaires 1 : ici, il n'y a plus d'état React du tout.

Le retour de l'attribut name mérite un paragraphe. Le module Formulaires 1 opposait le champ contrôlé (React détient la valeur dans un useState) au champ non contrôlé (le DOM la détient, on la relit à la soumission) ; avec une Server Action branchée sur action, on est franchement du côté non contrôlé : le navigateur collecte lui-même les champs et les identifie par leur name. Ce vieil attribut HTML, presque oublié à l'ère du tout-contrôlé, redevient le contrat entre ton balisage et ta fonction serveur — un name mal orthographié, et formData.get('date') rend null, sans la moindre erreur, juste un champ vide qui échoue à la validation.

Vient enfin l'argument qui emporte la décision, et que tu dois pouvoir sortir en entrevue : ce formulaire fonctionne sans JavaScript côté client. C'est l'amélioration progressive (progressive enhancement). Le HTML sait déjà soumettre un formulaire — une de ses fonctions les plus anciennes, antérieure à tout framework — et Next.js s'appuie dessus : le formulaire rendu côté serveur est un vrai <form> avec une vraie destination. Si le JavaScript n'a pas fini de charger, si le réseau est mauvais, si le bundle a planté, la soumission part quand même en POST HTML classique ; quand le JavaScript est là, React intercepte et améliore (pas de rechargement, état d'envoi, erreurs en place). La base fonctionne toujours, l'interactivité est un bonus — alors qu'un formulaire écrit avec onSubmit et fetch est un bouton mort tant que le bundle n'est pas chargé.

// app/reserver/page.tsx — Server Component
import { reserver } from '@/app/actions/reserver';

export default function BookingPage() {
  return (
    <form action={reserver}>
      <label htmlFor="date">Date</label>
      <input id="date" type="date" required />

      <label htmlFor="heure">Heure</label>
      <input id="heure" type="time" required />

      <button type="submit">Réserver</button>
    </form>
  );
}

Après la mutation : rafraîchir et rediriger

Une mutation qui réussit laisse un problème derrière elle : l'écran ment. La page « Mes rendez-vous » a été rendue avant la réservation, elle affiche une liste qui n'a plus cours. Comme l'a montré le module sur le rendu et le data fetching, ce qui a été mis en cache côté serveur — ou déjà rendu et gardé par le routeur pour les navigations suivantes — ne se rafraîchit pas tout seul : il faut dire explicitement à Next.js ce qui vient de devenir faux. D'où deux fonctions importées de next/cache, à appeler après l'écriture :

• revalidatePath('/mes-rendez-vous') — « les données de cette route sont périmées ». C'est l'outil du quotidien : tu sais quelle page affiche ce que tu viens de changer, tu la nommes.
• revalidateTag('appointments') — « toutes les données étiquetées ainsi sont périmées ». C'est ici que se referme la boucle ouverte dans le module Rendu & data fetching : l'étiquette que tu révoques est exactement celle que cacheTag('appointments') avait posée à la lecture. Même chaîne de caractères des deux côtés, sinon rien ne se passe — et rien ne t'avertira. Plus indirect que revalidatePath, mais plus juste quand la même donnée nourrit cinq pages différentes : tu invalides la donnée, pas la liste des écrans qui l'affichent. Le jour où une sixième page apparaît, elle est couverte sans que personne ait à y penser.

Et redirect('/mes-rendez-vous/57'), importé de next/navigation, envoie l'utilisateur ailleurs une fois le travail fait. Un détail qui surprend tout le monde une fois : redirect() fonctionne en levant une exception interne que Next.js intercepte — ne l'appelle donc jamais dans un try dont le catch avalerait tout, sinon tu attrapes le signal et rien ne se passe. Place-le après ton bloc try/catch.

L'ordre a du sens : on écrit, on invalide, on redirige. Invalider avant d'écrire ne sert à rien (on remettrait en cache l'ancienne valeur), et rediriger avant d'invalider fait arriver l'utilisateur sur une page encore périmée. Une chorégraphie en trois temps, toujours la même.

// LECTURE — app/creneaux/creneaux-caches.ts
import { cacheTag } from 'next/cache';

export async function lireCreneaux(serviceId: string) {
  'use cache';
  cacheTag('slots');                 // ← étiquette POSÉE ici
  return chargerCreneauxDepuisAgenda(serviceId);
}

// ÉCRITURE — app/actions/annuler.ts
'use server';

import { revalidateTag } from 'next/cache';

export async function annuler(id: string) {
  await cancelAppointment(id);
  revalidateTag('creneaux');         // ← étiquette RÉVOQUÉE ici
}

L'état d'une action côté interface

Le formulaire de la section « Les Server Actions : la deuxième voie » est fonctionnel, mais muet : si la validation échoue, l'utilisateur ne voit rien ; si l'envoi prend deux secondes, rien ne bouge et il reclique — et POST n'étant pas idempotent (module HTTP & fetch), deux clics peuvent produire deux réservations. Il manque les deux autres moments de toute opération asynchrone, « ça charge » et « ça a raté ». React 19 fournit un hook pour chacun.

useActionState encapsule l'action et te rend son résultat : tu lui donnes ta Server Action et un état initial, il te rend un triplet — l'état courant (ce que l'action a retourné la dernière fois), une action enveloppée à brancher sur le formulaire, et un booléen « en cours ». Contrepartie : ta Server Action reçoit alors un argument de plus, en première position, l'état précédent — sa signature devient (etatPrecedent, formData).

'use client';

import { useActionState } from 'react';
import { reserver } from '@/app/actions/reserver';
import { SubmitButton } from './SubmitButton';

const ETAT_INITIAL = { errors: {} as Record<string, string> };

export function BookingForm() {
  // etat   : ce que l'action a RETOURNÉ (ici { errors })
  // action : l'action enveloppée, à brancher sur le form
  // enCours: true pendant l'aller-retour serveur
  const [etat, action, enCours] = useActionState(reserver, ETAT_INITIAL);

  return (
    <form action={action}>
      <label htmlFor="date">Date</label>
      <input id="date" name="date" type="date" required />
      {/* L'erreur renvoyée par le SERVEUR, affichée sous le bon champ. */}
      {etat.errors.date && <p role="alert">{etat.errors.date}</p>}

      <SubmitButton />   {/* enfant : il lira l'état d'envoi lui-même */}
    </form>
  );
}

role="alert" : le module HTML sémantique & accessibilité expliquait qu'un lecteur d'écran annonce spontanément le contenu d'une région ainsi marquée. Une erreur qu'on ne peut pas entendre n'est pas affichée pour tout le monde.

useFormStatus (importé de react-dom) donne l'état d'envoi du formulaire parent. Il sert typiquement à désactiver le bouton pendant l'aller-retour — la protection anti-double-envoi dont on parlait à l'instant.

'use client';

import { useFormStatus } from 'react-dom';

export function SubmitButton() {
  // pending = "le <form> PARENT est en train d'envoyer"
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Envoi…' : 'Réserver'}
    </button>
  );
}

Un composant minuscule, dont l'existence même est la leçon de la section.

Pourquoi un composant séparé, alors qu'un disabled={enCours} dans le formulaire aurait suffi ? Parce que useFormStatus lit le <form> le plus proche au-dessus de lui dans l'arbre. Appelé dans le composant qui rend le formulaire, il ne trouve aucun formulaire parent — le <form> est son enfant, pas son ancêtre — et retourne éternellement pending: false : le bouton ne se désactive jamais, aucune erreur n'apparaît, et tu passes une heure à chercher. La règle est mécanique : le composant qui appelle useFormStatus doit être rendu à l'intérieur du <form>.

Le mécanisme repose sur une idée que tu connais depuis le guide Halterofit : un contexte React. Le <form> publie son état d'envoi à ses descendants et le hook s'y abonne ; or un contexte descend, il ne remonte jamais — d'où la contrainte. Bénéfice pratique : ton SubmitButton devient réutilisable dans n'importe quel formulaire de l'app, sans prop à lui passer.

'use client';

import { useFormStatus } from 'react-dom';
import { reserver } from '@/app/actions/reserver';

export function BookingForm() {
  const { pending } = useFormStatus();

  return (
    <form action={reserver}>
      <input id="date" name="date" type="date" required />

      <button type="submit" disabled={pending}>
        {pending ? 'Envoi…' : 'Réserver'}
      </button>
    </form>
  );
}

Route Handler ou Server Action ? Le tableau de décision

Voilà la question d'entrevue, et elle est parfaite pour évaluer un candidat : pas de réponse unique, il faut comprendre les deux mécanismes, et elle révèle si tu as réfléchi ou récité. Le critère de tri tient en une question : qui appelle ce code ? Si c'est « ma propre page, en réaction à un formulaire ou à un bouton », c'est une Server Action — on ne définit pas un contrat public pour un usage interne. Si c'est « quelqu'un d'autre » — une app mobile, un service tiers qui te POSTe un webhook quand un événement survient chez lui, un script, une autre équipe — c'est un Route Handler. Un contrat public a besoin d'une URL stable, d'une méthode, de statuts documentés : ce qu'une Server Action, dont l'endpoint est un identifiant généré par le compilateur, ne peut pas offrir.

La dernière ligne est la plus importante, et c'est le piège tendu aux candidats venus du monde purement client, dont le réflexe est « pour afficher des données, j'écris une route d'API et je la fetch depuis mon composant ». Dans l'App Router, c'est un aller-retour gratuit et nuisible : ton Server Component tourne déjà sur le serveur et peut interroger la base directement. Écrire GET /api/services pour que ta propre page se l'auto-appelle, c'est faire voyager la donnée du serveur au serveur en passant par HTTP. La route d'API se justifie quand un autre client en a besoin, pas par habitude.

Et rien n'oblige à choisir globalement : dans RendezVous, les formulaires internes passent par des Server Actions et /api/appointments existe en parallèle pour la future app mobile. Les deux appellent creerRendezVous — la fonction métier de la section « Où mettre la logique : le handler traduit, la fonction métier travaille ». Deux portes, un seul couloir.

Sécurité, sobrement

Pas de chapitre paniqué sur la cybersécurité — juste trois règles qu'un stagiaire frontend doit connaître, parce que leur absence se voit immédiatement en revue de code.

Un point d'entrée est public, point. Route Handler comme Server Action : dès que c'est déployé, c'est joignable, et toute vérification faite dans l'interface — bouton caché, route protégée, condition {user && ...} — est un confort d'utilisation, jamais une sécurité, puisque l'attaquant n'ouvre pas ta page mais envoie une requête. L'authentification (« qui es-tu ? ») et l'autorisation (« as-tu le droit ? ») se vérifient donc dans le corps de la fonction serveur, à chaque appel. Et souviens-toi du couple 401/403 du module HTTP & fetch : deux questions distinctes, et l'autorisation est celle qu'on oublie.

'use server';

export async function cancelAppointment(id: string) {
  // 1. AUTHENTIFICATION — qui es-tu ? (sinon : 401 / redirection connexion)
  const user = await utilisateurCourant();
  if (!user) redirect('/connexion');

  // 2. AUTORISATION — ce rendez-vous est-il bien LE TIEN ? (sinon : 403)
  //    C'est l'étape qu'on oublie : sans elle, changer l'id dans la requête
  //    suffit à annuler le rendez-vous de n'importe quel autre patient.
  const rdv = await lireRendezVous(id);
  if (!rdv || rdv.patientId !== user.id) {
    throw new Error('Accès refusé');
  }

  await annuler(id);
  revalidatePath('/mes-rendez-vous');
}

Cinq lignes de garde avant une ligne de travail. C'est le ratio normal d'une mutation, et personne ne trouvera ça excessif en revue.

Ne jamais faire confiance à ce qui arrive. C'est la leçon du module Formulaires 2, transposée : la validation côté client est une courtoisie (dire à l'utilisateur qu'il s'est trompé avant de le faire attendre), la validation côté serveur est la seule vraie. Corps de POST, FormData, query string, paramètre d'URL, identifiant passé à une action : tout vient de l'extérieur, tout se vérifie. Et vérifier ne veut pas seulement dire « le format est bon » — ça veut aussi dire « cet identifiant appartient à cet utilisateur », comme ci-dessus.

Les secrets restent côté serveur. Le module sur la carte de Next.js a posé la règle : sans le préfixe NEXT_PUBLIC_, une variable d'environnement n'est lisible que sur le serveur. Les Route Handlers et les Server Actions étant du code serveur, c'est là que doivent vivre les clés d'API, les jetons de service et les identifiants de base — un des grands bénéfices du modèle : ta clé secrète Stripe s'utilise sans jamais quitter le serveur.

Et le garde global ? Le fichier proxy.ts, présenté dans le module La carte de Next.js, intercepte bien les requêtes en amont — mais c'est l'endroit d'une redirection globale, pas d'un contrôle de droits fin : un garde de couloir ne dispense jamais de verrouiller les portes. Tes vérifications restent dans l'action.

{user.role === 'admin' && (
  <form action={exporterToutesLesReservations}>
    <button type="submit">Exporter (CSV)</button>
  </form>
)}

'use server';

export async function exporterToutesLesReservations() {
  // Le bouton n'est visible que pour les admins, donc on est tranquille.
  const toutes = await lireToutesLesReservations();
  return { csv: versCSV(toutes) };
}