Server Actions

Next.js integriert React Actions, um eine eingebaute Lösung für Server-Mutationen bereitzustellen.

Konvention

Sie können Server Actions in Ihrem Next.js-Projekt aktivieren, indem Sie das experimentelle Flag serverActions aktivieren.

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

Server Actions können an zwei Orten definiert werden:

• Innerhalb der Komponente, die sie verwendet (nur Server Components).
• In einer separaten Datei (Client- und Server Components), zur Wiederverwendbarkeit. Sie können mehrere Server Actions in einer einzelnen Datei definieren.

Mit Server Components

Erstellen Sie eine Server Action, indem Sie eine asynchrone Funktion mit der "use server"-Direktive am Anfang des Funktionskörpers definieren. "use server" stellt sicher, dass diese Funktion nur auf dem Server ausgeführt wird.

Diese Funktion sollte serialisierbare Argumente und einen serialisierbaren Rückgabewert haben.

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

Mit Client Components

Import

Erstellen Sie Ihre Server Action in einer separaten Datei mit der "use server"-Direktive am Anfang der Datei. Importieren Sie dann die Server Action in Ihre Client-Komponente:

'use server'

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

'use client'

import { myAction } from './actions'

export default function ClientComponent() {
  return (
    <form action={myAction}>
      <button type="submit">Zum Warenkorb hinzufügen</button>
    </form>
  )
}

Gut zu wissen: Wenn eine "use server"-Direktive auf oberster Ebene verwendet wird, gelten alle darunter exportierten Funktionen als Server Actions. Sie können mehrere Server Actions in einer einzelnen Datei haben.

Props

In einigen Fällen möchten Sie möglicherweise eine Server Action als Prop an eine Client-Komponente übergeben.

<ClientComponent updateItem={updateItem} />

'use client'

export default function ClientComponent({ myAction }) {
  return (
    <form action={myAction}>
      <input type="text" name="name" />
      <button type="submit">Element aktualisieren</button>
    </form>
  )
}

Argumente binden

Sie können Argumente an eine Server Action binden, indem Sie die bind-Methode verwenden. Dies ermöglicht es Ihnen, eine neue Server Action mit bereits gebundenen Argumenten zu erstellen. Dies ist nützlich, wenn Sie zusätzliche Argumente an eine Server Action übergeben möchten.

'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">Benutzernamen aktualisieren</button>
    </form>
  )
}

Dann erhält die updateUser-Server Action immer das userId-Argument zusätzlich zu den Formulardaten:

'use server'

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

Gut zu wissen: .bind einer Server Action funktioniert sowohl in Server- als auch in Client-Komponenten. Es unterstützt auch Progressive Enhancement.

Aufruf

Sie können Server Actions mit folgenden Methoden aufrufen:

• Mit action: Reacts action-Prop ermöglicht den Aufruf einer Server Action auf einem <form>-Element.
• Mit formAction: Reacts formAction-Prop ermöglicht die Behandlung von <button>, <input type="submit"> und <input type="image">-Elementen in einem <form>.
• Benutzerdefinierter Aufruf mit startTransition: Rufen Sie Server Actions ohne Verwendung von action oder formAction mit startTransition auf. Diese Methode deaktiviert Progressive Enhancement.

Progressive Enhancement

Progressive Enhancement ermöglicht es einem <form>, auch ohne JavaScript oder bei deaktiviertem JavaScript ordnungsgemäß zu funktionieren. Dies ermöglicht Benutzern die Interaktion mit dem Formular und das Absenden von Daten, auch wenn das JavaScript für das Formular noch nicht geladen wurde oder fehlschlägt.

React Actions (sowohl Server- als auch Client-Actions) unterstützen Progressive Enhancement mit einer von zwei Strategien:

• Wenn eine Server Action direkt an ein <form> übergeben wird, ist das Formular auch bei deaktiviertem JavaScript interaktiv.
• Wenn eine Client Action an ein <form> übergeben wird, ist das Formular weiterhin interaktiv, aber die Action wird in eine Warteschlange gestellt, bis das Formular hydratisiert ist. React priorisiert die Action, sodass sie dennoch schnell ausgeführt wird.

In beiden Fällen ist das Formular vor der Hydratisierung interaktiv. Obwohl Server Actions den zusätzlichen Vorteil haben, nicht auf Client-JavaScript angewiesen zu sein, können Sie dennoch zusätzliches Verhalten mit Client Actions kombinieren, ohne die Interaktivität zu beeinträchtigen.

Größenbeschränkung

Standardmäßig beträgt die maximale Größe des an eine Server Action gesendeten Request-Bodys 1MB, um die übermäßige Belastung der Serverressourcen durch das Parsen großer Datenmengen zu verhindern.

Sie können diese Beschränkung jedoch mit der Option serverActionsBodySizeLimit konfigurieren. Sie kann die Anzahl der Bytes oder ein beliebiges von bytes unterstütztes Zeichenfolgenformat annehmen, z.B. 1000, '500kb' oder '3mb'.

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

Zusätzliche Ressourcen

Die folgenden React-API-Seiten werden derzeit dokumentiert:

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