Tutoriel Next.js Server Actions : bonnes pratiques pour formulaires et validation

Devant l’écran, vous parcourez le code d’un formulaire d’inscription. Quatre fichiers empilés : composant formulaire, API Route, types, gestion d’erreurs… Pour une simple soumission, vous approchez les 200 lignes.

Existe-t-il une voie plus simple ?

Oui : les Server Actions. Cette fonctionnalité de l’App Router Next.js peut simplifier le flux de formulaires d’environ 80 %. Pas d’API Route, pas de fetch manuel, pas de gestion d’état laborieuse. Trop beau ? Vous vous demandez peut-être : est-ce vraiment sûr ? Comment valider ? Comment gérer le chargement ?

Au début, j’avais les mêmes doutes. Après quelques mois d’usage et quelques écueils, voici ce que j’ai retenu sur les Server Actions pour les formulaires — de la soumission de base à Zod, la sécurité et l’UX, avec des exemples concrets pour démarrer vite.

Bases des Server Actions

Qu’est-ce qu’une Server Action ?

Une Server Action est une fonction asynchrone côté serveur, marquée avec 'use server', utilisable directement dans l’attribut action d’un formulaire. À la soumission, elle est appelée automatiquement ; traitement, base de données, cache… tout se fait côté serveur.

Caractéristiques clés :

• Typage fort : TypeScript couvre toute la chaîne
• Zéro configuration : pas de dossier /api à créer
• Traitement automatique : FormData transmis automatiquement

Deux styles : inline dans le composant ou fichier dédié (recommandé) :

// Style 1 : inline dans le composant
export default function Page() {
  async function createUser(formData: FormData) {
    'use server' // marqueur Server Action
    const name = formData.get('name')
    // traitement...
  }

  return <form action={createUser}>...</form>
}

// Style 2 : fichier séparé (recommandé)
// app/actions.ts
'use server' // marqueur au niveau fichier

export async function createUser(formData: FormData) {
  const name = formData.get('name')
  // traitement...
}

Server Actions vs API Routes traditionnelles ? Quand choisir ?

En bref : Server Actions en interne, API Routes vers l’extérieur. Pour les formulaires de votre app, les Server Actions suffisent. Pour des interfaces tierces ou des GET, restez sur les API Routes.

Selon l’enquête Vercel 2025, 63 % des développeurs utilisent déjà les Server Actions en production. Ce n’est plus une fonctionnalité expérimentale.

"63 % des développeurs utilisent déjà les Server Actions en production"

Premier exemple de Server Action

Un formulaire de connexion minimal :

// app/login/page.tsx
export default function LoginPage() {
  async function handleLogin(formData: FormData) {
    'use server' // fonction serveur

    const email = formData.get('email') as string
    const password = formData.get('password') as string

    console.log('Tentative de connexion:', email)
    // en prod : vérification utilisateur, token, etc.
  }

  return (
    <form action={handleLogin}>
      <input
        type="email"
        name="email"
        placeholder="E-mail"
        required
      />
      <input
        type="password"
        name="password"
        placeholder="Mot de passe"
        required
      />
      <button type="submit">Connexion</button>
    </form>
  )
}

C’est tout. Points clés :

1. 'use server' : indique à Next.js d’exécuter la fonction côté serveur
2. formData.get() : récupère la valeur via l’attribut name
3. action={handleLogin} : appel automatique à la soumission

Résultat : clic sur Envoyer, pas de rechargement complet, données traitées côté serveur. Moins de fetch, useState, gestion d’erreurs…

Mais c’est le minimum. En production : validation, erreurs, chargement. Suite ci-dessous.

Validation de formulaires en pratique

Validation avec Zod

Se fier au required côté client ? Insuffisant. Les outils de développement du navigateur contournent facilement ces contrôles. La validation serveur est obligatoire.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

Zod valide le format côté serveur et renvoie des erreurs structurées avant toute écriture en base.

Installation :

npm install zod

Schéma et action :

// app/actions.ts
'use server'

import { z } from 'zod'

const SignupSchema = z.object({
  name: z.string().min(2, 'Le nom doit contenir au moins 2 caractères'),
  email: z.string().email('Format e-mail invalide'),
  password: z.string().min(8, 'Mot de passe : minimum 8 caractères'),
})

export async function signup(formData: FormData) {
  const rawData = {
    name: formData.get('name'),
    email: formData.get('email'),
    password: formData.get('password'),
  }

  const result = SignupSchema.safeParse(rawData)

  if (!result.success) {
    return {
      success: false,
      errors: result.error.flatten().fieldErrors,
    }
  }

  const { name, email, password } = result.data

  console.log('Création utilisateur:', { name, email })

  return {
    success: true,
    message: 'Inscription réussie !',
  }
}

Points clés :

1. safeParse sans exception : retourne { success: false, error: ... } en cas d’échec
2. flatten().fieldErrors : format { name: ['erreur1'], email: ['erreur2'] } pour l’affichage
3. Données structurées : success + erreurs pour guider le client

Comment afficher ces erreurs dans le formulaire ? Avec useActionState.

Afficher les erreurs : useActionState

useActionState (React 19, anciennement useFormState) gère l’état renvoyé par une Server Action. Il :

• stocke la réponse serveur dans l’état du composant ;
• fournit une action encapsulée ;
• indique si le formulaire est en cours de soumission.

// app/signup/page.tsx
'use client'

import { useActionState } from 'react'
import { signup } from '@/app/actions'

export default function SignupPage() {
  const initialState = { success: false, errors: {}, message: '' }

  const [state, formAction, isPending] = useActionState(signup, initialState)

  return (
    <form action={formAction}>
      <div>
        <label>Nom</label>
        <input
          type="text"
          name="name"
          required
        />
        {state.errors?.name && (
          <p className="error">{state.errors.name[0]}</p>
        )}
      </div>

      <div>
        <label>E-mail</label>
        <input
          type="email"
          name="email"
          required
        />
        {state.errors?.email && (
          <p className="error">{state.errors.email[0]}</p>
        )}
      </div>

      <div>
        <label>Mot de passe</label>
        <input
          type="password"
          name="password"
          required
        />
        {state.errors?.password && (
          <p className="error">{state.errors.password[0]}</p>
        )}
      </div>

      <button type="submit" disabled={isPending}>
        {isPending ? 'Envoi...' : "S'inscrire"}
      </button>

      {state.success && (
        <p className="success">{state.message}</p>
      )}
    </form>
  )
}

Flux :

1. Soumission → appel de signup
2. Échec validation → { success: false, errors: {...} }
3. useActionState met à jour state
4. Re-render avec les erreurs

isPending vaut true pendant la soumission — utile pour désactiver le bouton et afficher un libellé de chargement.

Note : après échec, les valeurs saisies peuvent disparaître. Vous pouvez renvoyer un champ values et utiliser defaultValue. L’essentiel : useActionState relie composant client et Server Action et simplifie la gestion d’état.

Optimisation de l’expérience utilisateur

État de chargement et anti double-soumission

isPending suffit souvent, mais il existe aussi useFormStatus. Facile à confondre au début.

En résumé :

• isPending de useActionState : dans le composant formulaire
• pending de useFormStatus : dans un sous-composant (ex. bouton)

useFormStatus doit être appelé dans un enfant de <form>, pas dans le composant formulaire lui-même. Utile pour extraire un bouton réutilisable.

// components/SubmitButton.tsx
'use client'

import { useFormStatus } from 'react-dom'

export function SubmitButton({ children }: { children: React.ReactNode }) {
  const { pending } = useFormStatus()

  return (
    <button
      type="submit"
      disabled={pending}
      className={pending ? 'loading' : ''}
    >
      {pending ? 'Envoi...' : children}
    </button>
  )
}

Dans le formulaire :

// app/signup/page.tsx
'use client'

import { useActionState } from 'react'
import { signup } from '@/app/actions'
import { SubmitButton } from '@/components/SubmitButton'

export default function SignupPage() {
  const [state, formAction] = useActionState(signup, { success: false, errors: {} })

  return (
    <form action={formAction}>
      {/* champs... */}

      <SubmitButton>S'inscrire</SubmitButton>

      {state.errors?.general && (
        <p className="error">{state.errors.general}</p>
      )}
    </form>
  )
}

Le bouton encapsule le chargement : désactivation anti double-clic, libellé « Envoi… », animation possible.

pending vs isPending ?

En pratique :

• logique complexe, plusieurs états → useActionState
• bouton générique → useFormStatus

Amélioration progressive

Les Server Actions supportent l’amélioration progressive : même sans JavaScript, le formulaire peut être soumis.

Next.js s’appuie sur la soumission native <form>. Avec JS, interception en requête AJAX ; sans JS, soumission classique.

Cas réels rares aujourd’hui, mais utile pour l’accessibilité et les crawlers. Rien à configurer : Next.js gère.

Sécurité et bonnes pratiques

Sécurité des Server Actions

Partie souvent négligée. Beaucoup pensent : « c’est côté serveur, donc sécurisé ». Faux.

Une Server Action est un endpoint API public. Next.js génère un ID difficile à deviner — obfuscation, pas sécurité réelle. Un regard dans l’onglet Réseau suffit pour trouver l’ID et appeler l’action manuellement.

Protections intégrées Next.js :

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

1. CSRF : POST uniquement ; vérification Origin/Host
2. ID d’action chiffré : difficile à énumérer
3. Variables de closure chiffrées si utilisées dans l’action

Insuffisant. Vous devez aussi :

1. Valider les entrées

Ne jamais faire confiance au client. Zod, comme vu plus haut.

2. Authentifier

Vérifier la session pour toute action protégée.

3. Autoriser

Connexion ≠ droits. L’utilisateur A ne doit pas supprimer les données de B.

Exemple complet :

// app/actions.ts
'use server'

import { cookies } from 'next/headers'
import { z } from 'zod'

const DeletePostSchema = z.object({
  postId: z.string().min(1),
})

export async function deletePost(formData: FormData) {
  const rawData = {
    postId: formData.get('postId'),
  }

  const result = DeletePostSchema.safeParse(rawData)
  if (!result.success) {
    return { success: false, error: 'Requête invalide' }
  }

  const { postId } = result.data

  const cookieStore = await cookies()
  const sessionToken = cookieStore.get('session')?.value

  if (!sessionToken) {
    return { success: false, error: 'Veuillez vous connecter' }
  }

  const currentUser = await getUserFromSession(sessionToken)
  if (!currentUser) {
    return { success: false, error: 'Session expirée' }
  }

  const post = await getPost(postId)
  if (!post) {
    return { success: false, error: 'Article introuvable' }
  }

  if (post.authorId !== currentUser.id) {
    return { success: false, error: 'Vous n\'avez pas le droit de supprimer cet article' }
  }

  await deletePostFromDB(postId)

  return { success: true, message: 'Suppression réussie' }
}

Validation → authentification → autorisation → exécution. Aucune étape ne peut manquer.

Outil utile : next-safe-action pour centraliser validation, auth et erreurs :

import { createSafeActionClient } from 'next-safe-action'

const actionClient = createSafeActionClient({
  async middleware() {
    const session = await getSession()
    if (!session) {
      throw new Error('Non connecté')
    }
    return { userId: session.userId }
  },
})

export const deletePost = actionClient
  .schema(DeletePostSchema)
  .action(async ({ parsedInput, ctx }) => {
    const { postId } = parsedInput
    const { userId } = ctx

    // suppression...
  })

Toutes les actions protégées partagent la même logique.

Rappel : une Server Action est un endpoint API. Mêmes exigences de sécurité qu’une route API classique.

Cas pratique : formulaire avec authentification

Formulaire de commentaire réservé aux utilisateurs connectés :

// app/actions.ts
'use server'

import { cookies } from 'next/headers'
import { z } from 'zod'
import { revalidatePath } from 'next/cache'

const CommentSchema = z.object({
  postId: z.string(),
  content: z.string().min(1, 'Le commentaire ne peut pas être vide').max(500, 'Maximum 500 caractères'),
})

export async function addComment(formData: FormData) {
  const rawData = {
    postId: formData.get('postId'),
    content: formData.get('content'),
  }

  const result = CommentSchema.safeParse(rawData)
  if (!result.success) {
    return {
      success: false,
      errors: result.error.flatten().fieldErrors,
    }
  }

  const cookieStore = await cookies()
  const sessionToken = cookieStore.get('session')?.value

  if (!sessionToken) {
    return {
      success: false,
      error: 'Connectez-vous pour commenter',
    }
  }

  const user = await getUserFromSession(sessionToken)
  if (!user) {
    return {
      success: false,
      error: 'Session expirée, reconnectez-vous',
    }
  }

  const { postId, content } = result.data

  await saveComment({
    postId,
    content,
    authorId: user.id,
    authorName: user.name,
    createdAt: new Date(),
  })

  revalidatePath(`/posts/${postId}`)

  return {
    success: true,
    message: 'Commentaire publié',
  }
}

Composant client :

// app/posts/[id]/CommentForm.tsx
'use client'

import { useActionState } from 'react'
import { addComment } from '@/app/actions'
import { SubmitButton } from '@/components/SubmitButton'

export function CommentForm({ postId }: { postId: string }) {
  const [state, formAction] = useActionState(addComment, {
    success: false,
    errors: {},
  })

  return (
    <form action={formAction}>
      <input type="hidden" name="postId" value={postId} />

      <textarea
        name="content"
        placeholder="Votre commentaire..."
        rows={4}
        required
      />

      {state.errors?.content && (
        <p className="error">{state.errors.content[0]}</p>
      )}

      {state.error && (
        <p className="error">{state.error}</p>
      )}

      {state.success && (
        <p className="success">{state.message}</p>
      )}

      <SubmitButton>Publier le commentaire</SubmitButton>
    </form>
  )
}

Zod, session, useActionState, revalidatePath, bouton avec chargement — flux prêt pour la production.

Techniques avancées

Passer des paramètres supplémentaires

Parfois il faut transmettre plus que les champs visibles — par ex. l’ID d’article à éditer.

Champ caché :

<input type="hidden" name="postId" value={postId} />

Ou bind, plus élégant :

// app/actions.ts
'use server'

export async function updatePost(postId: string, formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string

  await updatePostInDB(postId, { title, content })

  return { success: true }
}

Côté client :

// app/posts/[id]/edit/page.tsx
'use client'

import { updatePost } from '@/app/actions'

export default function EditPost({ postId }: { postId: string }) {
  const updatePostWithId = updatePost.bind(null, postId)

  return (
    <form action={updatePostWithId}>
      <input type="text" name="title" required />
      <textarea name="content" required />
      <button type="submit">Mettre à jour</button>
    </form>
  )
}

bind(null, postId) fixe postId comme premier argument ; FormData arrive en second.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Idéal pour édition, suppression, etc.

Revalidation des données

Après mutation, le cache des pages concernées peut être obsolète. Deux fonctions Next.js :

1. revalidatePath

Par chemin :

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  // création...

  revalidatePath('/')
  revalidatePath(`/posts/${newPostId}`)

  return { success: true }
}

2. revalidateTag

Par tag (défini sur le fetch) :

fetch('https://api.example.com/posts', {
  next: { tags: ['posts'] }
})

import { revalidateTag } from 'next/cache'

export async function createPost(formData: FormData) {
  // création...

  revalidateTag('posts')

  return { success: true }
}

Quand utiliser quoi ?

• Peu de chemins fixes → revalidatePath
• Données partagées sur plusieurs pages → revalidateTag

Je privilégie revalidatePath ; les tags quand une action touche beaucoup de pages.

Mise à jour optimiste

Pour des actions quasi toujours réussies (like, favori) : mettre à jour l’UI immédiatement, soumettre ensuite.

React 19 propose useOptimistic :

'use client'

import { useOptimistic } from 'react'
import { likePost } from '@/app/actions'

export function LikeButton({ postId, initialLikes }: { postId: string; initialLikes: number }) {
  const [optimisticLikes, setOptimisticLikes] = useOptimistic(initialLikes)

  async function handleLike() {
    setOptimisticLikes(optimisticLikes + 1)

    await likePost(postId)
  }

  return (
    <button onClick={handleLike}>
      👍 {optimisticLikes}
    </button>
  )
}

Clic → compteur +1 sans attendre le serveur.

Réservez cela aux opérations très fiables ; en cas d’échec, le rollback complique l’UX.

Conclusion

Trois points à retenir :

1. Les Server Actions simplifient les formulaires, sans tout remplacer. En interne oui ; API publiques → Route Handlers.

2. La sécurité vous appartient. Validation, auth, autorisation — le framework ne suffit pas.

3. Les détails UX comptent. Chargement, erreurs, optimisme… useActionState et useFormStatus couvrent l’essentiel.

Commencez simple : une Server Action, Zod, un état de chargement — vous maîtrisez déjà 80 %. Cache, optimisme : consultez la doc au besoin.

Next.js et React évoluent vite ; les API peuvent changer. Surveillez la documentation officielle.

Essayez dans votre projet : la prochaine soumission de formulaire sera peut-être bien plus simple qu’avant.