Actions Serveur

• Créer une Action Serveur à partir d’un Composant Serveur
• Importer des Actions Serveur depuis des Composants Client
• Composer les Actions Serveur au moyen des Actions
• Actions de formulaire et Actions Serveur
• Actions Serveur et useActionState
• Amélioration progressive avec useActionState

Lorsqu’une Action Serveur est définie au moyen d’une directive "use server", votre framework crée automatiquement une référence à la fonction serveur, et la passe au Composant Client. Lorsque cette fonction sera appelée côté client, React réagira en envoyant une requête au serveur pour exécuter cette fonction, et en renvoyant le résultat.

Les Actions Serveur peuvent être créées dans les Composants Serveur et passées comme props à des Composants Client, ou peuvent être directement importées et utilisées dans des Composants Client.

Créer une Action Serveur à partir d’un Composant Serveur

Les Composants Serveur peuvent définir des Actions Serveur au moyen de la directive "use server" :

// Composant Serveur
import Button from './Button';

function EmptyNote () {
  async function createNoteAction() {
    // Action Serveur
    'use server';
    
    await db.notes.create();
  }

  return <Button onClick={createNoteAction}/>;
}

Lorsque React affichera le Composant Serveur EmptyNote, il créera une référence à la fonction createNoteAction et passera cette référence au Composant Client Button. Lorsqu’on cliquera sur le bouton, React enverra la requête au serveur pour exécuter la fonction createNoteAction avec la référence fournie :

"use client";

export default function Button({onClick}) { 
  console.log(onClick); 
  // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'}
  return <button onClick={() => onClick()}>Créer une note vide</button>
}

Pour en savoir plus, consultez la documentation de "use server".

Importer des Actions Serveur depuis des Composants Client

Les Composants Client peuvent importer des Actions Serveur depuis des modules utilisant la directive "use server" :

"use server";

export async function createNoteAction() {
  await db.notes.create();
}

Lorsque le bundler construit le Composant Client EmptyNote, il injecte dans le bundle une référence à la fonction createNoteAction. Lorsqu’on cliquera sur le button, React enverra une requête au serveur pour exécuter la fonction createNoteAction au moyen de la référence fournie :

"use client";
import {createNoteAction} from './actions';

function EmptyNote() {
  console.log(createNoteAction);
  // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'}
  return <button onClick={createNoteAction} />
}

Pour en savoir plus, consultez la documentation de "use server".

Composer les Actions Serveur au moyen des Actions

Les Actions Serveur peuvent être composées avec des Actions côté client :

"use server";

export async function updateName(name) {
  if (!name) {
    return {error: 'Le nom est requis'};
  }
  await db.users.updateName(name);
}

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [name, setName] = useState('');
  const [error, setError] = useState(null);

  const [isPending, startTransition] = useTransition();

  const submitAction = async () => {
    startTransition(async () => {
      const {error} = await updateName(name);
      if (!error) {
        setError(error);
      } else {
        setName('');
      }
    })
  }
  
  return (
    <form action={submitAction}>
      <input type="text" name="name" disabled={isPending}/>
      {state.error && <span>Échec : {state.error}</span>}
    </form>
  )
}

Ça vous permet d’accéder à l’état isPending de l’Action Serveur en l’enrobant dans une Action côté client.

Pour en savoir plus, allez lire Appeler une Action Serveur hors d’un <form>.

Actions de formulaire et Actions Serveur

Les Actions Serveur peuvent interagir avec des fonctionnalités de formulaire de React 19.

Vous pouvez passer une Action Serveur à un formulaire pour envoyer automatiquement le formulaire au serveur :

"use client";

import {updateName} from './actions';

function UpdateName() {
  return (
    <form action={updateName}>
      <input type="text" name="name" />
    </form>
  )
}

Lorsque l’envoi du formulaire aura réussi, React réinitialisera automatiquement le formulaire. Vous pouvez ajouter useActionState pour accéder à l’état d’attente, consulter la dernière réponse connue, ou prendre en charge l’amélioration progressive.

Pour en savoir plus, allez lire Les Actions Serveur dans les formulaires.

Actions Serveur et useActionState

Vous pouvez composer des Actions Serveur avec useActionState pour le cas classique où vous avez juste besoin d’accéder à l’état en attente de l’action et à sa dernière réponse connue :

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [state, submitAction, isPending] = useActionState(updateName, {error: null});

  return (
    <form action={submitAction}>
      <input type="text" name="name" disabled={isPending}/>
      {state.error && <span>Échec : {state.error}</span>}
    </form>
  );
}

Lorsque vous utilisez useActionState avec des Actions Serveur, React rejoue automatiquement les envois de formulaire réalisés avant la fin de l’hydratation. Ça signifie que les utilisateurs peuvent interagir avec votre appli avant même qu’elle soit hydratée.

Pour en savoir plus, consultez la documentation de useActionState.

Amélioration progressive avec useActionState

Les Actions Serveur prennent aussi en charge l’amélioration progressive grâce au troisième argument de useActionState.

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [, submitAction] = useActionState(updateName, null, `/name/update`);

  return (
    <form action={submitAction}>
      ...
    </form>
  );
}

Lorsqu’un permalien est fourni à useActionState, React redirigera sur l’URL fournie si le formulaire est envoyé avant que le bundle JavaScript soit chargé.

Apprenez-en davantage dans la documentation de useActionState.