Next.js App Router: So ziehen Sie die Grenze zwischen Server und Client Component

Teamstandard für die ‘use client’-Grenze im Next.js App Router, datenleckende Props, Cache-Absicht, Berechtigungsprüfung in Server Actions und Messung der Bundle-Größe.
Technische Zusammenfassung
Technologie
Next.js App Router, React Server Components, Server Actions, TypeScript
Thema
Grenze zwischen Server- und Client-Komponenten und Datenfluss
Niveau
Mittel bis fortgeschritten
Voraussetzungen
  • Kenntnisse zu React-Komponenten und Hooks
  • Grundlegende Next.js-Projektstruktur
  • TypeScript-Grundkenntnisse
In diesem Beitrag7 Abschnitte

Ein Großteil der Probleme, die in Code-Reviews von Next.js-App-Router-Projekten auftauchen, hat dieselbe Ursache: Die 'use client'-Grenze sitzt an der falschen Stelle. Die Anwendung läuft, die Bildschirme öffnen sich; aber das an den Client gesendete JavaScript bläht sich auf, die Datenbankabfrage wandert in den Browser, und interne Notizen zu einem Kunden werden im Netzwerkverkehr sichtbar. Dieser Leitfaden verbindet für Teams, die Unternehmens-Geschäftsanwendungen entwickeln, die Trennung von Server und Client Component, die Cache-Absicht und die Sicherheit von Server Actions zu einem einzigen Teamstandard.

Das Modell des App Routers

Im Pages Router wurde eine Seite als Ganzes auf dem Server gerendert und im Browser hydriert; Daten kamen über Funktionen auf Seitenebene wie getServerSideProps oder getStaticProps. Der App Router (Verzeichnis app/) bringt dieses Modell auf Komponentenebene: Jede Komponente unter app/ ist standardmäßig eine React Server Component. Die Komponente kann asynchron sein, direkt auf die Datenquelle zugreifen, und ihre Ausgabe geht nicht als JavaScript, sondern als serialisiertes Renderergebnis (RSC-Payload) an den Browser.

Dateikonventionen sind Teil dieses Modells: layout.tsx definiert die dauerhafte Hülle, page.tsx den Inhalt der Route, loading.tsx den Suspense-Fallback, error.tsx die Fehlergrenze, route.ts den HTTP-Endpunkt. error.tsx muss dabei eine Client Component sein. Die Grenze begegnet Ihnen schon in der ersten Datei. Die Auswirkung von Render-Strategien auf die Suchmaschinensichtbarkeit ist ein eigenes Thema; dazu der Beitrag React, SSR, SSG und technisches SEO. Hier liegt der Fokus auf der Komponentenarchitektur.

Unterschied zwischen Server Component und Client Component

Beide Komponententypen nutzen dieselbe JSX-Syntax, ihre Fähigkeiten sind aber fast gegensätzlich. Für die Entscheidung ist diese Tabelle ein ausreichender Anfang:

Bedarf Server Component Client Component
Zugriff auf Datenbank, interne API, Dateisystem Geeignet Nicht geeignet
Geheimer Schlüssel, Token, Verbindungszeichenfolge Geeignet Niemals
useState, useEffect, Event-Handler Nicht verwendbar Geeignet
window, localStorage, Browser-APIs Nicht verwendbar Geeignet
Große Formatierungs-/Markdown-Bibliothek Bevorzugt (gelangt nicht ins Bundle) Vergrößert das Bundle
Context-Provider (Theme, Query-Client) Nicht direkt Erforderlich

Der in der Praxis am häufigsten verwechselte Punkt: Auch eine Client Component wird bei der ersten Anfrage auf dem Server zu HTML gerendert und dann im Browser hydriert. Das Etikett „Client“ bedeutet nicht „läuft nur im Browser“, sondern „ihr Code wird auch an den Browser gesendet“. Deshalb muss der Zugriff auf window oder localStorage in einer Client Component innerhalb von useEffect erfolgen. Sonst erhalten Sie beim Server-Rendering einen Fehler oder eine Hydration-Abweichung.

Wohin gehört die ‘use client’-Grenze?

Die Direktive 'use client' markiert keine Komponente, sondern eine Modulgrenze. Die Datei mit der Direktive und jedes Modul, das diese Datei importiert, gelangen ins Client-Bundle. Die Regel ist einfach: Setzen Sie die Direktive so nah wie möglich an die Blätter des Baums.

Die Struktur, die wir in Unternehmens-Webanwendungen für einen typischen Bestelllisten-Bildschirm empfehlen:

app/
  (panel)/
    bestellungen/
      page.tsx            // Server: ruft Daten ab, rendert die Tabelle
      loading.tsx         // Server: Skelettansicht
      actions.ts          // 'use server': Mutationen
      _components/
        BestellTabelle.tsx   // Server: erzeugt die Zeilen
        StatusFilter.tsx     // 'use client': select + router
        FreigabeButton.tsx   // 'use client': useActionState
lib/
  db.ts                   // import 'server-only'
  bestell-service.ts      // import 'server-only'

Die meisten Grenzfehler verhindern diese drei Regeln:

  • Eine Server Component kann eine Client Component importieren; umgekehrt geht es nicht. Braucht eine Client Component eine Server-Komponente, übergeben Sie diese von außen als children oder als anderes Prop. Mit diesem „Loch“-Muster bleibt etwa der Inhalt eines clientseitigen Ausklappbereichs serverseitig gerendert.
  • Props, die die Grenze passieren, müssen serialisierbar sein. Einfache Objekte, Arrays, Strings, Zahlen und Date gehen durch; Klasseninstanzen und gewöhnliche Funktionen nicht. Müssen Sie eine Funktion übergeben, muss sie eine Server Action sein.
  • Sperren Sie serverseitige Module. Gerät ein Modul, das das Paket server-only importiert, versehentlich in eine Client-Component-Kette, schlägt der Build fehl. Die erste Zeile jeder Datei der Datenzugriffsschicht sollte diese sein.
// lib/bestell-service.ts
import 'server-only';
import { db } from './db';

export async function bestellungenAbrufen(firmaId: string) {
  return db.bestellung.findMany({
    where: { firmaId },
    select: { id: true, nr: true, status: true, betrag: true },
  });
}

Das select im Beispiel ist kein Zufall. Jedes Prop, das von einer Server Component an eine Client Component geht, erreicht den Browser innerhalb der RSC-Payload. Übergeben Sie den gesamten Benutzerdatensatz an eine Client-Komponente, lassen sich Passwort-Hash, interne Notizen oder Kostenfelder im Netzwerk-Tab lesen, auch wenn sie nicht angezeigt werden. Nicht sichtbar heißt nicht geheim. Für Umgebungsvariablen gilt dieselbe Logik: Nur Variablen mit dem Präfix NEXT_PUBLIC_ werden ins Client-Bundle eingebettet; geben Sie dieses Präfix niemals geheimen Werten.

Datenabruf und Cache-Verhalten

Im App Router werden Daten in der Server Component, die sie nutzt, mit await abgerufen. Brauchen mehrere Komponenten im selben Render dieselben Daten, verhindert eine mit Reacts Funktion cache umhüllte Datenfunktion doppelte Abfragen pro Anfrage. Starten Sie voneinander unabhängige Aufrufe parallel mit Promise.all; eine Kette aufeinanderfolgender await erzeugt Wasserfall-Latenz und ist die klassische Ursache langsamer Seiten.

Caching ist der Teil des App Routers, der sich zwischen Versionen am stärksten geändert hat. In Next.js 14 wurden fetch-Aufrufe standardmäßig gecacht; mit Next.js 15 wurde Nicht-Cachen zum Standard; in neueren Versionen kamen ein optionales Cache-Komponentenmodell und die Direktive 'use cache' hinzu. Auf einen so wechselhaften Standard ist kein Verlass. Schreiben Sie als Teamstandard die Absicht bei jedem Aufruf explizit aus:

Absicht Entsprechung im App Router
Frische Daten bei jeder Anfrage fetch(url, { cache: 'no-store' })
In bestimmten Abständen erneuerte Daten fetch(url, { next: { revalidate: 300 } })
Ereignisgesteuerte Erneuerung next: { tags: ['produkte'] } + revalidateTag('produkte') (in Next.js 16 wird als zweites Argument ein Cache-Profil erwartet, z. B. 'max')
Dynamisches Rendering auf Routenebene export const dynamic = 'force-dynamic'
Pfadbasierte Erneuerung revalidatePath('/bestellungen')

In Unternehmens-Geschäftsanwendungen besteht das eigentliche Risiko darin, dass benutzer- oder firmenspezifische Daten in einen gemeinsam genutzten Cache gelangen. Eine Route, die cookies() oder headers() liest, wird dynamisch gerendert; vergessen Sie aber beim Umhüllen von per ORM abgerufenen Daten mit unstable_cache oder einem ähnlichen Mechanismus, die Mandanten-/Firmen-ID in den Cache-Schlüssel aufzunehmen, können Daten einer Firma einer anderen angezeigt werden. Das ist kein Performancefehler, sondern ein Datenleck. Prüfen Sie im Code-Review bei jeder Änderung, die berechtigungsabhängige Daten cacht, zusätzlich, ob der Schlüssel die Identitätsinformation enthält. Ab Next.js 15 sind cookies(), headers() und die Seitenwerte params asynchron und müssen mit await gelesen werden.

Formularverarbeitung mit Server Actions

Eine Server Action ist eine mit der Direktive 'use server' markierte asynchrone Serverfunktion, die vom Client aus aufgerufen werden kann. An das Prop action eines <form>-Elements übergeben, funktioniert sie auch ohne geladenes JavaScript (progressive Verbesserung) und macht für die meisten internen Formulare eine separate API-Route überflüssig.

// app/(panel)/bestellungen/actions.ts
'use server';
import { z } from 'zod';
import { revalidatePath } from 'next/cache';
import { sitzungAbrufen } from '@/lib/auth';
import { bestellungFreigeben } from '@/lib/bestell-service';

const Eingabe = z.object({ bestellungId: z.string().uuid() });

export async function freigeben(_vorher: unknown, formData: FormData) {
  const sitzung = await sitzungAbrufen();
  if (!sitzung || !sitzung.rollen.includes('Genehmiger')) {
    return { fehler: 'Für diesen Vorgang fehlt Ihnen die Berechtigung.' };
  }
  const ergebnis = Eingabe.safeParse({ bestellungId: formData.get('bestellungId') });
  if (!ergebnis.success) return { fehler: 'Ungültige Anfrage.' };

  await bestellungFreigeben(ergebnis.data.bestellungId, sitzung.benutzerId);
  revalidatePath('/bestellungen');
  return { fehler: null };
}

Clientseitig verwaltet der Hook useActionState von React 19 den Rückgabewert und den Wartezustand der Aktion; useFormStatus aus react-dom deaktiviert den Button im Formular während des Sendens. Das aus älteren Beispielen bekannte useFormState wurde durch useActionState abgelöst.

Die am häufigsten übersehene Eigenschaft von Server Actions: Beim Build wird für jede Aktion eine ID erzeugt, und die Aktion verhält sich wie ein Endpunkt, der unter dieser ID POST-Anfragen annimmt. Sie ist also nach außen offen. Den Button nur berechtigten Benutzern anzuzeigen, ist keine Sicherheitsprüfung; jemand kann die Anfrage auch manuell senden. Berechtigungs- und Eingabeprüfung erfolgen wie im Beispiel innerhalb der Aktion. Wie Sie Validierung mit demselben Schema auf Client und Server aufbauen, beschreibt der Beitrag Validierung in Webformularen ausführlich.

Häufige Fehler und Kontrolle der Bundle-Größe

Fehler, die uns in Code-Reviews immer wieder begegnen, und ihre Korrekturen:

  • 'use client' zum Root-Layout hinzufügen: Geschieht meist für einen Theme- oder Query-Provider und verwandelt die ganze Anwendung in eine Client-Komponente. Richtig: Lagern Sie den Provider in eine separate Client Component Providers.tsx aus und umhüllen Sie im Layout {children} damit. Children werden weiterhin auf dem Server gerendert.
  • Abweichung bei Datum und Locale: Weicht die Zeitzone des Servers von der des Browsers ab, erzeugt new Date().toLocaleString() eine Hydration-Warnung. Formatieren Sie Datumswerte auf dem Server mit einer festen Zeitzone (Intl.DateTimeFormat + timeZone: 'Europe/Istanbul').
  • Datenabruf unnötig auf den Client verlagern: Die Daten der ersten Ansicht mit useEffect abzurufen, bedeutet leeren Bildschirm, Ladeanzeige und einen zusätzlichen Roundtrip. Die ersten Daten sollen vom Server kommen; clientseitige Datenbibliotheken bleiben für nachträglich aktualisierte, interaktionsabhängige Daten. Diese Trennung behandelt der Beitrag Zustandsverwaltung in React.
  • Schwere Bibliothek im Client importieren: Nutzen Sie next/dynamic, um Komponenten wie Diagramme, Rich-Text-Editor oder PDF-Viewer erst bei Bedarf zu laden.
  • Die ganze Seite wegen einer langsamen Abfrage warten lassen: Umhüllen Sie den langsamen Teil mit <Suspense>; der Rest der Seite kommt per Streaming sofort.

Ein Bundle, das Sie nicht messen, können Sie nicht kontrollieren. Da sich die Größenangaben in der Ausgabe von next build von Version zu Version ändern (in neueren Versionen entfielen die Größenspalten pro Route), binden Sie die Messung an ein Analysewerkzeug. In mit Webpack gebauten Projekten leistet das Plugin @next/bundle-analyzer gute Dienste; bei Versionen, die mit Turbopack bauen, sehen Sie in der Dokumentation Ihrer Version nach der Option zur Bundle-Analyse:

npm i -D @next/bundle-analyzer

// next.config.mjs
import bundleAnalyzer from '@next/bundle-analyzer';
const withBundleAnalyzer = bundleAnalyzer({ enabled: process.env.ANALYZE === 'true' });
export default withBundleAnalyzer({});

// ausfuehren
ANALYZE=true npm run build

Damit die Grenze mit der Zeit nicht verwischt, schreiben Sie diese Prüfungen in den Teamstandard:

  • Module für Datenzugriff und geheime Konfiguration beginnen mit import 'server-only'.
  • Für jede Datei mit 'use client' wird im Code-Review die Frage „Warum Client?“ beantwortet.
  • An Client Components wird nicht das vollständige Datenmodell, sondern nur die vom Bildschirm benötigten Felder übergeben.
  • Jede Server Action prüft intern Sitzung, Berechtigung und Eingabe.
  • Die Cache-Absicht (frisch, zeitgesteuert, getaggt) ist bei jedem Datenaufruf explizit angegeben.
  • Die JavaScript-Größe pro Route im Bundle-Analysebericht wird zwischen Versionen verglichen.

Ist noch nicht klar, ob der App Router das richtige Werkzeug für Ihr Projekt ist, sehen Sie sich zuerst den Vergleich WordPress oder Next.js an. Beim Umzug einer bestehenden Anwendung auf diese Architektur oder beim Entwurf eines neuen internen Systems können wir Komponentengrenzen und Cache-Strategie im Rahmen unserer Leistung Webanwendungen mit React und Next.js gemeinsam planen. Für API-Details sind die offizielle Next.js-App-Router-Dokumentation und Reacts Referenzseite zu Server Components maßgeblich.

Häufig gestellte Fragen

Warum ist es problematisch, eine ganze Seite mit ‘use client’ zu markieren?

Die Direktive führt dazu, dass die Datei und alle von ihr importierten Module in das Client-Bundle gelangen. Datenabruf wandert in den Browser, Bibliotheken, die auf dem Server bleiben könnten, werden heruntergeladen, und das Risiko steigt, dass geheime Konfiguration in Client-Code gelangt. Lagern Sie den interaktiven Teil in eine kleine separate Komponente aus und markieren Sie nur diese.

Kann man in einer Server Component useState oder useEffect verwenden?

Nein. Eine Server Component wird nur auf dem Server gerendert (zur Anfragezeit oder beim Build); ihr Code läuft nie im Browser. Alles, was Zustand, Effekte und Browser-APIs braucht, gehört in eine Client Component. Die Server Component ruft die Daten ab und gibt das Ergebnis als Prop an eine interaktive Client Component weiter.

Ersetzt eine Server Action einen API-Endpunkt?

Für die eigenen Formulare und Mutationen der Anwendung meist ja. Für mobile Clients, Integrationen oder Drittanbieter-Konsumenten wird dennoch eine versionierbare HTTP-API (Route Handler oder separater Dienst) gebraucht. Da sich Server Actions wie nach außen offene POST-Endpunkte verhalten, müssen Eingabevalidierung und Berechtigungsprüfung in jeder Aktion separat erfolgen.

Warum wirkt das Cache-Verhalten von Version zu Version anders?

Next.js hat das Standard-Caching des App Routers in Hauptversionen geändert; mit Next.js 15 etwa werden fetch-Anfragen standardmäßig nicht mehr gecacht, in späteren Versionen kamen optionale neue Cache-Modelle hinzu. Maßgeblich ist die Dokumentation der Version in Ihrem Projekt; schreiben Sie die Cache-Absicht bei jedem Datenaufruf explizit aus.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge