8. Next.js I - Struktur und Routing

Next.js I: Struktur und Routing

React rendert Komponenten, mehr nicht. Für eine echte Anwendung fehlt einiges: mehrere Seiten mit URLs, ein Server, der sie ausliefert, ein Build-Prozess, der TypeScript und JSX übersetzt, und später ein Ort für die eigene API. All das könnte man einzeln zusammenstecken; ein Framework liefert es fertig verdrahtet. Der Lehrplan verlangt die Entwicklung komplexer Anwendungssysteme “unter Verwendung von Frameworks und Middleware”, und unser Framework ist Next.js: der verbreitetste Rahmen um React, der Client und Server in einem Projekt vereint.

Die Begriffe sauber getrennt: Eine Bibliothek (React) wird von unserem Code aufgerufen; ein Framework (Next.js) ruft unseren Code auf und gibt die Struktur vor, in die er sich einfügt. Diese Umkehrung der Kontrolle ist das Wesen jedes Frameworks, und sie erklärt, warum ein Framework Konventionen hat, die man lernt statt diskutiert.

Projekt anlegen

1. Projekt erzeugen:

   npx create-next-app@latest render-farm

   Die Fragen des Assistenten: TypeScript ja, ESLint ja, App Router ja, der Rest nach Geschmack (Tailwind wird in den Beispielen nicht vorausgesetzt).

2. Entwicklungsserver starten:

   cd render-farm
   npm run dev

   Die Anwendung läuft auf http://localhost:3000 und lädt bei jeder Dateiänderung automatisch neu (Hot Reload).

3. Struktur ansehen. Die wichtigsten Bestandteile:

   render-farm/
   ├── app/               # pages, layouts, later API routes
   │   ├── layout.tsx     # root layout (html, body, navigation)
   │   └── page.tsx       # the start page /
   ├── public/            # static files (images, favicon)
   ├── package.json       # scripts and dependencies
   ├── next.config.ts     # framework configuration
   └── tsconfig.json      # TypeScript, preconfigured strict

Bemerkenswert ist, was fehlt: kein Webpack-Setup, keine tsc-Aufrufe, kein Server-Skript. Das Framework übernimmt Build, TypeScript und Serverbetrieb; npm run dev für die Entwicklung, npm run build und npm start für den Produktionsbetrieb.

Was ist Webpack?

Ein Browser versteht kein TypeScript, kein JSX und keine über viele Dateien verstreuten import-Anweisungen. Ein Bundler übersetzt diesen Quellcode in wenige, browserlesbare JavaScript-Dateien und fügt die vielen Module zu einem Paket (“Bundle”) zusammen. Webpack ist der über Jahre verbreitetste solche Bundler. Früher musste man ihn von Hand konfigurieren; Next.js bringt einen fertig eingerichteten Bundler mit, deshalb taucht er in unserem Projekt nirgends auf.

App Router: Ordner sind Routen

Next.js leitet die URLs der Anwendung aus der Ordnerstruktur unter app/ ab. Ein Ordner ist ein URL-Segment, die Datei page.tsx darin macht das Segment zur aufrufbaren Seite:

app/
├── page.tsx                  ->  /
├── jobs/
│   ├── page.tsx              ->  /jobs
│   └── [id]/
│       └── page.tsx          ->  /jobs/42, /jobs/7, ...
└── presets/
    └── page.tsx              ->  /presets

Eine Seite ist eine gewöhnliche React-Komponente als Default-Export:

app/jobs/page.tsx

export default function JobsPage() {
  return <h1>Render jobs</h1>;
}

Dynamische Segmente stehen in eckigen Klammern: Der Ordner [id] fängt jeden Wert an dieser Stelle, und die Seite erhält ihn über die params-Prop (in aktuellen Next-Versionen als Promise, daher await):

app/jobs/[id]/page.tsx

export default async function JobDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return <h1>Job {id}</h1>;
}

Damit ist das URL-Schema aus dem API-Entwurfskapitel direkt abbildbar: Sammlung unter /jobs, Element unter /jobs/42. Für unbekannte Pfade liefert Next automatisch einen 404; eine eigene Datei not-found.tsx gestaltet ihn.

Layouts: der gemeinsame Rahmen

Eine Datei layout.tsx umschließt alle Seiten ihres Ordners und aller Unterordner. Das Wurzel-Layout trägt das HTML-Gerüst und die Navigation, die auf jeder Seite erscheint:

app/layout.tsx

import Link from "next/link";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="de">
      <body>
        <nav>
          <Link href="/">Start</Link>
          <Link href="/jobs">Jobs</Link>
          <Link href="/presets">Presets</Link>
        </nav>
        <main>{children}</main>
      </body>
    </html>
  );
}

children ist die jeweils aktive Seite; das Layout selbst bleibt beim Seitenwechsel erhalten (samt seinem Zustand, etwa einem geöffneten Menü). Layouts verschachteln sich: Ein zusätzliches app/jobs/layout.tsx umschließt nur die Jobs-Seiten, innerhalb des Wurzel-Layouts. Navigiert wird mit der Link-Komponente statt <a>: Sie wechselt die Seite ohne komplettes Neuladen und lädt Ziele im Hintergrund vor. Dieses Wurzel-Layout mit Navigation ist ab jetzt das gemeinsame Gerüst, in dem alle weiteren Übungen dieses Jahres wohnen.

<Link> statt <a>

Ein klassisches <a href="/jobs"> löst beim Klick ein komplettes Neuladen aus: Der Browser wirft die aktuelle Seite weg, fordert die Ziel-URL vollständig vom Server an, baut das gesamte HTML neu auf und startet das JavaScript von vorn. Jeder Zustand im Speicher — ein offenes Menü, ein halb ausgefülltes Formular — geht dabei verloren.

<Link href="/jobs"> rendert zwar ebenfalls ein <a>-Element (Rechtsklick, “in neuem Tab öffnen” und Barrierefreiheit funktionieren also normal), fängt den Klick aber ab und erledigt den Wechsel in JavaScript. Next.js tauscht nur den Seiteninhalt (children) aus, während das Layout stehen bleibt. Das nennt man Client-seitige Navigation. Konkret tut Link drei Dinge mehr als ein rohes <a>:

• Kein Full-Reload: Nur der Inhaltsbereich wird ersetzt, das Layout und dessen Zustand überleben den Wechsel.
• Prefetching: Sobald ein Link im sichtbaren Bereich auftaucht, lädt Next.js den Code der Ziel-Seite schon im Hintergrund. Beim Klick ist sie oft bereits da und erscheint praktisch verzögerungsfrei.
• Aktiver Zustand: In Kombination mit dem Hook usePathname() lässt sich leicht erkennen, welcher Link zur aktuellen Seite gehört, um ihn etwa hervorzuheben.

Faustregel: Für Ziele innerhalb der eigenen Anwendung immer <Link>; für externe Adressen (https://…) bleibt das gewöhnliche <a> richtig.

Server- und Client-Komponenten

Jetzt zur Frage, die den Rest des Jahres begleitet: Wo läuft mein Code? Next.js führt Komponenten an zwei Orten aus, und der Unterschied ist keine Nebensache, sondern das Architekturmerkmal des Frameworks. Als Einstieg ordnet das folgende Video die beiden Komponentenarten und ihre Aufgaben ein:

Abspielen

Server-Komponenten sind der Standard: Jede Komponente ohne besondere Markierung wird auf dem Server gerendert, und nur das fertige HTML erreicht den Browser. Server-Komponenten dürfen deshalb Dinge, die im Browser undenkbar wären: direkt auf Dateien und (später) Datenbanken zugreifen, mit Geheimnissen wie API-Schlüsseln arbeiten, und sie dürfen async sein:

// app/presets/page.tsx: a server component reading a file
import { readFile } from "node:fs/promises";

export default async function PresetsPage() {
  const raw = await readFile("data/presets.json", "utf-8");
  const presets: string[] = JSON.parse(raw);
  return (
    <ul>
      {presets.map((preset) => <li key={preset}>{preset}</li>)}
    </ul>
  );
}

Genau dieses Vorgehen heißt Server-Side Rendering (SSR): Der Server erzeugt die Daten, rendert daraus fertiges HTML und schickt es an den Browser, der es sofort anzeigt und anschließend interaktiv macht (“hydriert”). Der folgende Ablauf zeigt die vier Schritte von der Anfrage bis zur fertigen, interaktiven Seite:

Abb. 8.1: Server-Side Rendering (SSR). Der Server erzeugt Daten und fertiges HTML und sendet es an den Client, der es sofort anzeigt und anschließend hydriert.

Client-Komponenten laufen im Browser und beginnen mit der Direktive "use client" in der ersten Zeile. Nur sie können, was Interaktivität braucht: Hooks (useState, useEffect, …), Event-Handler (onClick, onChange), Browser-APIs (localStorage).

// app/jobs/job-filter.tsx: interactivity needs the client
"use client";

import { useState } from "react";

export function JobFilter({ names }: { names: string[] }) {
  const [query, setQuery] = useState("");
  const visible = names.filter((n) => n.includes(query));
  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <ul>{visible.map((n) => <li key={n}>{n}</li>)}</ul>
    </>
  );
}

Das Gegenstück zu SSR ist Client-Side Rendering (CSR): Der Server liefert nur ein minimales HTML-Gerüst und das JavaScript-Bundle; erst im Browser rendert die durch "use client" markierte Komponente den tatsächlichen Inhalt. Der Ablauf verschiebt die Renderarbeit damit auf die Client-Seite:

Abb. 8.2: Client-Side Rendering (CSR). Der Server liefert nur minimales HTML und das JavaScript-Bundle; das eigentliche Rendern der Inhalte geschieht erst im Browser.

Die Entscheidungstabelle:

Bedarf	Server	Client
Daten laden (Datei, Datenbank, interne API)	ja	über HTTP
Geheimnisse (Schlüssel, Zugangsdaten)	ja	niemals
Hooks, Events, Interaktivität	nein	ja
Browser-APIs (localStorage, …)	nein	ja

Das Standardmuster kombiniert beide: Eine Server-Komponente beschafft die Daten und übergibt sie als Props an eine Client-Komponente, die die Interaktivität übernimmt (genau so arbeiten PresetsPage und JobFilter zusammen). Zwei Regeln dazu: "use client" wirkt ansteckend (alles, was eine Client-Komponente importiert, wird Teil des Client-Bundles), deshalb sitzt die Direktive so tief wie möglich im Komponentenbaum, nicht am Layout. Und die Grenze ist eine Sicherheitsgrenze: Was eine Client-Komponente als Prop erhält, steht im Browser und damit jedem Besucher offen; Geheimnisse bleiben auf der Server-Seite.

Wie dieses Zusammenspiel konkret aussieht und wo die Grenze zwischen Server und Client im Code verläuft, führt das folgende Video vor:

Abspielen

Sichtbar machen, wo Code läuft

Setzen Sie in eine Server- und eine Client-Komponente je ein console.log("rendering ..."). Die Server-Ausgabe erscheint im Terminal (dort, wo npm run dev läuft), die Client-Ausgabe in der Browser-Konsole. Dieses kleine Experiment beantwortet die Wo-läuft-mein-Code-Frage empirisch und ist bei jeder Verwirrung der schnellste Test.

Statisch oder dynamisch: wann der Server rendert

SSR sagt, wo gerendert wird (auf dem Server). Es bleibt aber eine zweite Frage: wann? Beim npm run build entscheidet Next.js das für jede Seite selbst, und es gibt zwei Möglichkeiten:

• Statisch (static): Die Seite wird einmal zur Bauzeit gerendert, das fertige HTML wird gespeichert und an jeden Besucher unverändert ausgeliefert. Sehr schnell, aber der Inhalt ist ab dem Build eingefroren. Das ist der Standardfall, immer wenn eine Seite von nichts Veränderlichem abzuhängen scheint.
• Dynamisch (dynamic): Die Seite wird bei jeder Anfrage neu auf dem Server gerendert. Etwas langsamer, dafür immer aktuell.

Im Build-Bericht stehen beide markiert, ○ für statisch, ƒ für dynamisch:

Route (app)
┌ ○ /                     (statisch, zur Bauzeit gerendert)
├ ƒ /jobs                 (dynamisch, pro Anfrage gerendert)
└ ○ /about                (statisch)

Meist trifft Next.js die richtige Wahl von allein: Sobald eine Seite etwas erkennbar Veränderliches nutzt (Daten aus einer Datenbank, das Lesen von headers() oder cookies(), ein fetch ohne Zwischenspeicher), schaltet sie automatisch auf dynamisch. Kniffelig wird es nur, wenn eine Seite veränderliche Daten liest, Next.js das aber nicht erkennt - etwa eine gewöhnliche Modul-Variable, die sich zur Laufzeit ändert. Dann baut Next.js die Seite fälschlich statisch und friert sie auf den Zustand zur Bauzeit ein. Für genau diesen Fall gibt es einen ausdrücklichen Schalter, den man aus der Datei exportiert:

app/jobs/page.tsx

export const dynamic = "force-dynamic";   // immer pro Anfrage rendern, nie einfrieren

export const dynamic = "force-dynamic" ist keine gewöhnliche Programmlogik, sondern eine Deklaration an das Framework: eine von mehreren Konstanten (dynamic, revalidate, runtime, …), die eine page.tsx oder route.ts exportieren kann und die Next.js beim Bauen ausliest. In den meisten Anwendungen braucht man sie nie, weil ein echter Datenzugriff die Seite ohnehin dynamisch macht. Man greift dazu, wenn eine Seite sichtbar veraltet, obwohl sich die Daten geändert haben - ein sicheres Zeichen, dass sie versehentlich statisch gebaut wurde.

Hydration: vom HTML zur interaktiven Seite

Bei SSR erreicht den Browser zuerst fertiges HTML. Es ist sofort sichtbar und lesbar, aber noch tot: Ein Klick auf einen Button bewirkt nichts, ein onChange feuert nicht, useState hält noch keinen Zustand. Der Grund ist einfach: Das HTML ist nur die Beschreibung der Oberfläche; die Ereignis-Handler und der Zustand leben im JavaScript, das erst noch geladen und ausgeführt werden muss.

Diesen zweiten Schritt nennt man Hydration (Hydrieren, wörtlich “mit Wasser versorgen”): React lädt im Browser das Client-Bundle, geht das bereits vorhandene HTML durch, hängt an jedes Element die passenden Event-Handler und stellt den Komponentenzustand her. Erst danach ist die Seite interaktiv. Wichtig ist, dass React das HTML dabei nicht neu aufbaut, sondern das vom Server gelieferte übernimmt und nur “belebt” — genau deshalb ist SSR schnell sichtbar und am Ende voll interaktiv.

Daraus folgen zwei Dinge, die in der Praxis regelmäßig auffallen:

• Die Reihenfolge ist sichtbar. Zwischen “HTML da” und “hydriert” liegt eine kurze Spanne. In dieser Zeit sieht der Benutzer die Seite schon, ein Klick geht aber noch ins Leere. Bei kleinen Seiten ist das kaum wahrnehmbar, bei großen Client-Bundles kann es spürbar werden — ein Grund, das Client-Bundle klein zu halten.
• Server- und Client-Ausgabe müssen übereinstimmen. React erwartet, dass das im Browser erzeugte HTML exakt zu dem passt, was der Server geschickt hat. Wer beim ersten Rendern etwas verwendet, das auf Server und Client verschieden ist — Date.now(), Math.random(), localStorage, window —, erhält einen Hydration-Mismatch: React meldet in der Konsole, dass sich Server- und Client-HTML unterscheiden. Solche Werte gehören deshalb nicht in das erste Rendern, sondern in einen useEffect, der erst nach der Hydration im Browser läuft.

Häufige Falle: Zeit und Zufall

Ein <p>{new Date().toLocaleTimeString()}</p> mitten in einer Komponente ist der Klassiker: Der Server rendert eine Uhrzeit, der Browser eine minimal andere, und React beschwert sich über einen Hydration-Mismatch. Lösung: den zeit- oder zufallsabhängigen Wert nach der Hydration im Browser setzen (useState + useEffect), sodass Server und Client mit demselben Ausgangswert starten.

Wie weit "use client" reicht

"use client" markiert nicht eine einzelne Komponente, sondern eine Grenze im Komponentenbaum. Die Direktive steht ganz oben in einer Datei und erklärt: Ab hier — in dieser Komponente und in allem, was sie importiert und rendert — sind wir auf der Client-Seite. Deshalb heißt es, "use client" sei “ansteckend”: Der ganze Teilbaum unterhalb der Grenze wird Teil des Client-Bundles, auch Komponenten, die selbst gar kein "use client" tragen.

Betrachten wir einen Baum mit einem interaktiven Zweig:

RootLayout            (Server)
└── DashboardPage     (Server)
    ├── StatsPanel    (Server)
    └── JobFilter     "use client"  ← Grenze
        ├── SearchBox         (im Client-Bundle)
        └── ResultList        (im Client-Bundle)
            └── ResultRow      (im Client-Bundle)

JobFilter setzt die Direktive. Damit landen SearchBox, ResultList und ResultRow automatisch im Client-Bundle — nicht, weil sie selbst markiert wären, sondern weil sie unterhalb der Grenze liegen. StatsPanel dagegen ist ein Geschwister von JobFilter, kein Kind, und bleibt eine reine Server-Komponente. RootLayout und DashboardPage bleiben ebenfalls auf dem Server.

Zwei Regeln machen den Umgang damit beherrschbar:

• Die Grenze so tief wie möglich setzen. Je weiter oben "use client" steht, desto größer der Teilbaum, der in den Browser wandert. Steht die Direktive versehentlich im Wurzel-Layout, wird die gesamte Anwendung zur Client-Anwendung, und der Vorteil der Server-Komponenten ist verloren. Deshalb sitzt "use client" am kleinsten wirklich interaktiven Baustein.

• Server-Inhalte über children durch die Grenze reichen. Angenommen, wir wollen einen aufklappbaren Rahmen (Accordion, interaktiv, also Client) um eine Statistik (ServerStats, liest Daten vom Server). Entscheidend ist der Unterschied zwischen importieren und übergeben.

  Der naheliegende, aber falsche Weg: Die Client-Komponente importiert die Server-Komponente direkt.

  accordion.tsx

  "use client";
  import { useState } from "react";
  import { ServerStats } from "./server-stats"; // imported directly
  export function Accordion() {
    const [open, setOpen] = useState(false);
    return (
      <div>
        <button onClick={() => setOpen(!open)}>Details</button>
        {open && <ServerStats />}   {/* pulls ServerStats into the client bundle */}
      </div>
    );
  }

  Durch den import liegt ServerStats unterhalb der Client-Grenze und wird Teil des Client-Bundles — der Server-Vorteil ist weg (und Datei-/Datenbankzugriff in ServerStats würde jetzt gar nicht mehr funktionieren).

  Der richtige Weg: Accordion importiert ServerStats nicht, sondern nimmt beliebigen Inhalt als children entgegen. Zusammengesteckt werden beide erst eine Ebene höher, in einer Server-Komponente.

  accordion.tsx

  "use client";
  import { useState } from "react";
  export function Accordion({ children }: { children: React.ReactNode }) {
    const [open, setOpen] = useState(false);
    return (
      <div>
        <button onClick={() => setOpen(!open)}>Details</button>
        {open && children}   {/* renders whatever it is given, without knowing it */}
      </div>
    );
  }
  
  // page.tsx  (server component)
  export default function DashboardPage() {
    return (
      <Accordion>
        <ServerStats />   {/* rendered here, in a server context */}
      </Accordion>
    );
  }

  Weil <ServerStats /> in page.tsx (Server) steht und nicht in accordion.tsx (Client), rendert der Server es fertig und übergibt nur das Ergebnis als children. Accordion steuert lediglich, ob dieser fertige Inhalt angezeigt wird — nicht, wie er entsteht. So bleibt ServerStats eine echte Server-Komponente, obwohl sie optisch in einem interaktiven Client-Rahmen sitzt.

Selbst nachsehen, was im Client landet

Nach npm run build meldet Next.js pro Route die Größe des First Load JS. Verschiebt man ein "use client" weiter nach oben oder unten im Baum und baut erneut, ändert sich diese Zahl sichtbar. Das ist die direkteste Rückmeldung darauf, wie weit die Client-Grenze tatsächlich reicht.

Lernergebnisse: Was Sie nach diesem Kapitel können sollten

Nach Abschluss dieses Kapitels sollten Schülerinnen und Schüler in der Lage sein:

• Erklären: den Unterschied zwischen Bibliothek und Framework erklären und benennen, welche Aufgaben Next.js gegenüber purem React übernimmt.
• Anwenden: ein Next.js-Projekt anlegen, den Entwicklungsserver nutzen und die Projektstruktur erklären.
• Anwenden: Seiten über die Ordnerstruktur anlegen, dynamische Segmente ([id]) auslesen und mit Link navigieren.
• Anwenden: gemeinsame Rahmen als (verschachtelte) Layouts umsetzen.
• Erklären: Server- und Client-Komponenten unterscheiden, die Entscheidungsregeln anwenden und begründen, warum Geheimnisse nie den Client erreichen dürfen.
• Erklären: statisches und dynamisches Rendern unterscheiden und erkennen, wann eine Seite export const dynamic = "force-dynamic" braucht.
• Entwerfen: Seiten so in Server- und Client-Anteile zerlegen, dass Interaktivität und Datenbeschaffung am jeweils richtigen Ort liegen.

Passende Übungen

• Aufgabe 14 - Mehrseiter mit Next.js