Actions de formulaire : remplacer les routes d’API pour les mutations

Dans les applications Next.js traditionnelles, les soumissions de formulaire nécessitent un composant client avec un gestionnaire onSubmit qui appelle fetch() pour envoyer les données par POST à une route d’API. Ce modèle fonctionne, mais il nécessite d’écrire et de maintenir séparément la logique de récupération côté client et le gestionnaire de route côté serveur.

Avec les actions serveur, vous remplacez l’appel de récupération et la route d’API par une seule fonction. L’élément de formulaire reçoit l’action serveur comme propriété action : <form action={serverAction}>. React intercepte la soumission et appelle automatiquement l’action avec les données du formulaire.

L’action serveur reçoit automatiquement un objet FormData comme argument lorsqu’elle est déclenchée par un formulaire. Vous accédez aux champs individuels avec formData.get('email'), qui renvoie la valeur sous forme de chaîne. Toutes les méthodes standard de FormData sont disponibles, notamment getAll() pour les champs à sélection multiple.

Une action serveur peut renvoyer une valeur sérialisable que le client peut utiliser. Renvoyer un objet d’erreur comme { error: 'Email already exists' } ou un indicateur de réussite comme { success: true } permet au client de mettre à jour l’interface en conséquence sans recharger entièrement la page.

Comme l’action du formulaire est une action serveur, le composant de page qui contient le formulaire n’a pas besoin d’être un composant client. Le serveur affiche le formulaire sous forme de HTML statique, et seules les parties interactives, comme l’affichage des erreurs, nécessitent du JavaScript côté client. Cela réduit considérablement la taille du paquet client.

Un formulaire avec action={serverAction} fonctionne même si JavaScript est désactivé. Le navigateur effectue une requête POST de formulaire HTML standard, le serveur exécute l’action, puis renvoie la page mise à jour. Cette véritable amélioration progressive permet au formulaire de se dégrader correctement dans tous les environnements.

Après qu’une action serveur a modifié des données, les données de page mises en cache doivent être actualisées. L’appel à revalidatePath('/dashboard') dans l’action invalide le cache de Next.js pour ce chemin, ce qui oblige la requête suivante à récupérer des données à jour. Il s’agit de la méthode standard pour maintenir à jour les pages rendues côté serveur après des modifications.

revalidateTag('user-data') fournit une invalidation du cache plus précise que revalidatePath. Vous associez des balises aux appels de récupération avec next: { tags: ['user-data'] }, puis vous invalidez toutes les données portant cette balise en une seule fois depuis l’action serveur, quels que soient les chemins qui les affichent.

Les actions serveur peuvent rediriger l’utilisateur vers une nouvelle page après une modification réussie en appelant redirect('/success') depuis le module next/navigation. Cette redirection est gérée côté serveur, ce qui signifie que le navigateur reçoit une réponse de navigation appropriée plutôt qu’une redirection côté client.

Les actions serveur ne se limitent pas aux soumissions de formulaire. Pour les clics sur des boutons et les autres déclencheurs sans formulaire, encapsulez l’appel de l’action dans startTransition(() => action(arg)). Cela marque la navigation comme une transition et permet à React de conserver l’interface actuelle visible pendant l’exécution de l’action sur le serveur.

Les actions serveur sont l’endroit approprié pour effectuer la validation côté serveur. Validez les champs de FormData, renvoyez les erreurs de validation s’ils ne sont pas valides et ne procédez à la modification que si tous les champs sont valides. Des bibliothèques comme Zod s’intègrent bien à cette approche : analysez FormData selon un schéma typé et renvoyez la carte des erreurs en cas d’échec.

Que reçoit une action serveur comme argument lorsqu’elle est déclenchée par une soumission de formulaire ?

Les actions serveur remplacent le modèle associant récupération et route d’API pour les modifications effectuées par un formulaire. La propriété action du formulaire accepte directement une action serveur, qui reçoit un objet FormData. Les actions renvoient des résultats sérialisables pour mettre à jour l’interface client, prennent en charge revalidatePath et revalidateTag pour l’invalidation du cache, et fonctionnent progressivement sans JavaScript.