Was passiert bei npm run build? Die Next.js-Pipeline

Würdigung — die „Magic" hinter dem grünen Häkchen#

In der klassischen WordPress-Welt gibt es keinen Build im engeren Sinn: PHP läuft live auf dem Server, die Seite wird bei jeder Anfrage neu zusammengebaut. Das funktioniert, hat aber den Preis, dass Tippfehler im PHP-Code oder ein neues Plugin-Update erst auf der Live-Site auffallen können. Eine moderne Site geht den umgekehrten Weg: Sie wird vorher gebaut, in einem definierten Schritt, und nur das fertige Ergebnis (statisches HTML, optimierte Assets) landet auf dem Server. Der Build ist damit der zentrale Qualitäts-Gate vor der Veröffentlichung.

Das macht die Site nicht magisch — es macht sie überprüfbar. Wenn der Build grün ist, ist eine ganze Reihe von Eigenschaften nachweisbar erfüllt; wenn er rot ist, ist klar, an welcher Stufe was schiefging.

Schritt 1: TypeScript-Typprüfung#

Sobald der Build startet (npm run build ruft bei Next.jsNext.js · zum GlossarReact-Framework für SSG/SSR/ISR — der aktuelle Standard für moderne Kanzlei-Sites. intern next build auf), läuft als allererstes der TypeScript-Compiler über das gesamte Projekt — bei uns mit strikter Einstellung. Was er prüft: Sind alle Typen konsistent? Ruft eine Komponente eine andere mit den richtigen Argumenten auf? Existiert das Feld description, das eine Funktion gerade liest? Verweist ein Insight-Cluster auf einen Slug, den es gar nicht gibt?

Diese Prüfung fängt eine sehr typische Klasse von Fehlern: Refactorings, die irgendwo unvollständig blieben. „Ich habe ein Feld umbenannt, aber an drei Stellen vergessen" — TypeScriptTypeScript · zum GlossarJavaScript mit statischer Typprüfung — fängt Tippfehler und Datenform-Bruch beim Build statt im Produktivbetrieb. zeigt diese drei Stellen mit Datei und Zeile an, bevor der Build überhaupt weitermacht. Details zum konkreten Mehrwert für Kanzlei-Sites: TypeScript-Insight.

Schritt 2: ESLint (Code-Standards + Barrierefreiheit)#

Wenn die Typen stimmen, läuft ESLintESLint · zum GlossarStatischer Code-Analyzer für JavaScript/TypeScript — fängt Style-Brüche und Anti-Patterns. mit den konfigurierten Regeln — bei uns der Default-Satz für Next.js + TypeScript, ergänzt um ein spezialisiertes Barrierefreiheits-Plugin (jsx-a11y). Dieses Plugin prüft schon beim Build automatisch, ob die Seite die anerkannten Barrierefreiheits-Regeln einhält — damit sie auch für Menschen nutzbar bleibt, die auf Screenreader oder reine Tastatur-Navigation angewiesen sind. ESLint fängt:

• Code-Geruch: tote Variablen, unbenutzte Importe, problematische Sprach-Konstrukte (z. B. == statt ===).
• React-spezifische Probleme: falsch verwendete Hooks, fehlende Schlüssel in Listen, gefährliche Render-Muster.
• Barrierefreiheits-Verstöße: <img> ohne alt, <button> ohne erkennbaren Text, Eingabefelder ohne Label.

Im Pre-Commit-Hook läuft ESLint nur auf den gestageten Dateien (Tempo); im Build läuft es über das ganze Projekt (Vollständigkeit) — eine sinnvolle Aufteilung.

Schritt 3: Bundle (Next.js Compiler)#

Jetzt erst entsteht der eigentliche Code, der später ausgeliefert wird. Next.js verarbeitet alle TypeScript-Dateien zu ausführbarem JavaScript, sammelt zugehöriges CSS (bei uns Tailwind), löst Importe auf, optimiert das Ergebnis (entfernt toten Code, minimiert) und teilt den Output in passende Pakete pro Route. Das Ziel: Pro Seite ein möglichst kleines, gezielt geladenes Bundle.

Für eine Kanzlei-Site ist dieser Schritt vor allem für die Core Web Vitals wichtig: Je kleiner das pro Seite geladene JavaScript, desto schneller die Anzeige beim Besucher.

Schritt 4: Statisches Rendering (SSG)#

Dies ist der Schritt, der eine moderne Kanzlei-Site fundamental von einer WordPress-Site unterscheidet. Next.js rendert jede Route, die keine Live-Daten braucht, schon zur Build-Zeit zu fertigem HTML. Bei uns betrifft das praktisch alle Seiten: Startseite, jede Stadt-Landingpage, jeder Insight-Artikel, jede Rubrik. Das Ergebnis sind statische HTML-Dateien, die später vom CDNCDN · zum GlossarContent Delivery Network — globales Netzwerk an Edge-Servern, das statische Inhalte ortsnah ausliefert. ausgeliefert werden — ohne Datenbank, ohne PHP, ohne Live-Logik.

Konsequenzen für Kanzlei-Sites:

• Tempo: Statisches HTML erscheint in Millisekunden im Browser, weil kein Server-seitiges Rendering wartet.
• Sicherheit: Was keine laufende Datenbank und keine laufende Anwendung hat, lässt sich auch nicht über klassische CMS-Angriffe übernehmen — der häufigste Angriffsvektor entfällt strukturell. Tiefer: Statisches Rendering vs. WordPress.
• Verlässlichkeit: Was beim Build geprüft wurde, ist auch das, was live ist — keine Inkonsistenz zwischen „lokal grün, live rot".

Schritt 5: Sitemap + OG-Image-Generierung#

Während dieser Stufe entstehen auch automatische Begleit-Dateien: die XML-Sitemap (die wir programmatisch aus den vorhandenen Routen erzeugen), die robots.txt, die Open-Graph-Bilder für Social-Sharing (bei uns über die Edge-Funktion opengraph-image.tsx jeweils pro Insight individuell generiert).

Das ist nicht trivial: Eine Sitemap, die manuell gepflegt werden muss, läuft fast garantiert aus dem Takt. Eine Sitemap, die beim Build aus den realen Routen entsteht, kann das nicht — sie ist per Konstruktion aktuell.

Schritt 6: Asset-Optimierung#

Schließlich werden die Assets, die mit der Site ausgeliefert werden, optimiert: Bilder in modernen Formaten (WebPWebP · zum GlossarModernes Bildformat — 25–35 % kleiner als JPEG bei gleicher Qualität., AVIFAVIF · zum GlossarNoch effizienteres Bildformat als WebP — 30–50 % kleiner, in Top-Browsern verfügbar., beschrieben im Bild-Optimierungs-Insight), Schriften (self-hosted und mit font-display: swap, beschrieben im Fonts-Insight), CSS und JavaScript komprimiert. Das Ergebnis-Verzeichnis (/.next/ bei uns) enthält am Ende alle Dateien, die später vom CDN ausgeliefert werden.

Was im Fehler-Fall passiert#

Hier wird die Pipeline wirklich nützlich. Wenn irgendeine Stufe scheitert — ein Typfehler, ein ESLint-Verstoß, ein Render-Problem bei einer statischen Seite —, bricht der Build ab. Konkrete Konsequenzen:

• Lokal: Der Entwickler sieht den Fehler sofort und kann ihn beheben.
• Im Vercel-Deploy (siehe Vercel-Deploy-Insight): Wenn der Build der neuen Version scheitert, wird die Live-Site NICHT überschrieben. Sie läuft mit der vorherigen, funktionierenden Version weiter. Das ist die fundamentale Sicherheit einer modernen Deployment-Pipeline: Eine kaputte Änderung wird nicht aktiv, eine funktionierende bleibt.

Das ist der eigentliche Grund, warum „Build muss grün sein" so eine Mantra-Position hat: Es ist die Stelle, an der Probleme noch repariert werden, bevor sie Besucher sehen.

Was Kanzleien davon haben#

Drei Vorteile, die sich aus der Pipeline selbst ergeben:

• Die Site geht nicht in Wartung, weil ein Plugin-Update schiefgegangen ist — dieser Fehler-Modus existiert in der statischen Welt strukturell nicht.
• Inhaltliche Inkonsistenzen werden früh sichtbar: Wenn die Sitemap aus realen Routen kommt und der Cluster-Linter Slug-Konsistenz erzwingt, fallen tote Verweise beim Build auf, nicht erst beim Besucher.
• Audit-Tauglichkeit: Eine Site, deren Build-Pipeline einen klaren Soll-Stand definiert (alle Routen erfolgreich gerendert, keine TypeScript-Fehler, keine A11y-Verstöße aus jsx-a11y, alle Assets optimiert), ist auch im Audit klar bewertbar — der Auditor kann fragen „läuft der Build aktuell grün?", und das ist eine objektiv beantwortbare Frage.

Wie wir es bauen#

Bei jedem neuen Projekt richten wir die Pipeline so ein, dass alle sechs Schritte aktiv sind — und prüfen, dass der Build lokal und in der Cloud (VercelVercel · zum GlossarHosting-Plattform für moderne Web-Apps — Standard-Heimat für Next.js-Sites mit EU-Region.) identisch grün läuft, bevor irgendetwas live geht. Wir ergänzen eigene Linter-Schritte (Cluster-Coverage, DSE-Konsistenz), wo das Risiko es rechtfertigt, und behalten die Build-Zeit unter zwei Minuten — schneller als das schließt die Lücke „der Build ist mir zu langsam, ich überspringe ihn manchmal".

Für eine strukturierte Bewertung der Build-Pipeline einer bestehenden Kanzlei-Site empfehlen wir den Hebel-Audit (890 €, bei Mandanten-Boost-Beauftragung innerhalb von 60 Tagen voll anrechenbar).

Zusammenfassung#

npm run build ist nicht eine einzelne Aktion, sondern eine Kette von etwa sechs nacheinander laufenden Schritten: TypeScript-Typprüfung, ESLint inkl. Barrierefreiheits-Plugin, Bundle-Erzeugung durch den Next.js-Compiler, statisches Rendering aller Seiten zu HTML, Sitemap- und OG-Image-Generierung, Asset-Optimierung. Jeder Schritt kann den Build stoppen — und das ist der eigentliche Mehrwert: Fehler werden vor der Veröffentlichung sichtbar, eine kaputte Änderung überschreibt nie eine funktionierende Live-Site, und der Soll-Stand der Pipeline ist objektiv prüfbar. Für Kanzlei-Sites ergibt sich daraus eine fundamental andere Sicherheits- und Verlässlichkeits-Lage als bei klassischen, live gerenderten CMS-Sites — die häufigsten Angriffs- und Ausfall-Wege existieren strukturell nicht.

Quellen#

• Next.js — next build CLI Reference — abgerufen 2026-06-05
• Next.js — Static Site Generation (SSG) — abgerufen 2026-06-05
• Vercel — Build Step Documentation — abgerufen 2026-06-05
• eslint-plugin-jsx-a11y — Repository — abgerufen 2026-06-05

Disclaimer: Beschreibung der tatsächlichen Build-Pipeline von fahoch2.de (Next.js 16, App Router, statisch gerendert) zum Zeitpunkt der Veröffentlichung. Konkrete Pipeline-Schritte sind framework-abhängig; das Prinzip „vor der Veröffentlichung prüfen, im Fehler-Fall die Live-Site schützen" bleibt gleich.