Actions serveur (Server Actions)

Next.js s'intègre avec les actions React pour fournir une solution intégrée pour les mutations côté serveur.

Convention

Vous pouvez activer les actions serveur (Server Actions) dans votre projet Next.js en activant le flag expérimental serverActions.

module.exports = {
  experimental: {
    serverActions: true,
  },
}

Les actions serveur peuvent être définies à deux endroits :

• À l'intérieur du composant qui l'utilise (uniquement pour les composants serveur).
• Dans un fichier séparé (pour les composants client et serveur), pour une meilleure réutilisabilité. Vous pouvez définir plusieurs actions serveur dans un seul fichier.

Avec les composants serveur

Créez une action serveur en définissant une fonction asynchrone avec la directive "use server" en haut du corps de la fonction. "use server" garantit que cette fonction ne sera exécutée que sur le serveur.

Cette fonction doit avoir des arguments sérialisables et une valeur de retour sérialisable.

export default function ServerComponent() {
  async function myAction() {
    'use server'
    // ...
  }
}

Avec les composants client

Importation

Créez votre action serveur dans un fichier séparé avec la directive "use server" en haut du fichier. Ensuite, importez l'action serveur dans votre composant client :

'use server'

export async function myAction() {
  // ...
}

'use client'

import { myAction } from './actions'

export default function ClientComponent() {
  return (
    <form action={myAction}>
      <button type="submit">Ajouter au panier</button>
    </form>
  )
}

Bon à savoir : Lorsque vous utilisez une directive "use server" de haut niveau, toutes les exportations en dessous seront considérées comme des actions serveur. Vous pouvez avoir plusieurs actions serveur dans un seul fichier.

Props

Dans certains cas, vous pourriez vouloir passer une action serveur à un composant client en tant que prop.

<ClientComponent updateItem={updateItem} />

'use client'

export default function ClientComponent({ myAction }) {
  return (
    <form action={myAction}>
      <input type="text" name="name" />
      <button type="submit">Mettre à jour l'élément</button>
    </form>
  )
}

Liaison d'arguments

Vous pouvez lier des arguments à une action serveur en utilisant la méthode bind. Cela vous permet de créer une nouvelle action serveur avec certains arguments déjà liés. Ceci est utile lorsque vous voulez passer des arguments supplémentaires à une action serveur.

'use client'

import { updateUser } from './actions'

export function UserProfile({ userId }) {
  const updateUserWithId = updateUser.bind(null, userId)

  return (
    <form action={updateUserWithId}>
      <input type="text" name="name" />
      <button type="submit">Mettre à jour le nom</button>
    </form>
  )
}

Ensuite, l'action serveur updateUser recevra toujours l'argument userId, en plus des données du formulaire :

'use server'

export async function updateUser(userId, formData) {
  // ...
}

Bon à savoir : .bind d'une action serveur fonctionne à la fois dans les composants serveur et client. Il prend également en charge l'amélioration progressive.

Invocation

Vous pouvez invoquer des actions serveur en utilisant les méthodes suivantes :

• Utilisation de action : La prop action de React permet d'invoquer une action serveur sur un élément <form>.
• Utilisation de formAction : La prop formAction de React permet de gérer les éléments <button>, <input type="submit"> et <input type="image"> dans un <form>.
• Invocation personnalisée avec startTransition : Invoquez des actions serveur sans utiliser action ou formAction en utilisant startTransition. Cette méthode désactive l'amélioration progressive.

Amélioration progressive

L'amélioration progressive permet à un <form> de fonctionner correctement sans JavaScript, ou avec JavaScript désactivé. Cela permet aux utilisateurs d'interagir avec le formulaire et de soumettre des données même si le JavaScript du formulaire n'a pas encore été chargé ou s'il échoue à se charger.

Les actions React (à la fois côté serveur et client) prennent en charge l'amélioration progressive, en utilisant l'une des deux stratégies suivantes :

• Si une action serveur est passée directement à un <form>, le formulaire est interactif même si JavaScript est désactivé.
• Si une action client est passée à un <form>, le formulaire reste interactif, mais l'action sera placée dans une file d'attente jusqu'à ce que le formulaire soit hydraté. React priorise l'action, donc elle se produit rapidement.

Dans les deux cas, le formulaire est interactif avant l'hydratation. Bien que les actions serveur aient l'avantage supplémentaire de ne pas dépendre du JavaScript côté client, vous pouvez toujours composer un comportement supplémentaire avec des actions client si nécessaire, sans sacrifier l'interactivité.

Limite de taille

Par défaut, la taille maximale du corps de la requête envoyée à une action serveur est de 1 Mo, pour éviter la consommation excessive de ressources serveur lors de l'analyse de grandes quantités de données.

Cependant, vous pouvez configurer cette limite en utilisant l'option serverActionsBodySizeLimit. Elle peut prendre un nombre d'octets ou toute chaîne de caractères supportée par bytes, par exemple 1000, '500kb' ou '3mb'.

module.exports = {
  experimental: {
    serverActions: true,
    serverActionsBodySizeLimit: '2mb',
  },
}

Ressources supplémentaires

Les pages d'API React suivantes sont actuellement en cours de documentation :

• "use server"
• action (🚧)
• formAction (🚧)
• useFormStatus (🚧)
• useFormState (🚧)
• useOptimistic (🚧)