Clean Architecture in Next.js: Struktur für Enterprise-Projekte
Verliere dich nicht im Spaghetti-Code. Wir zeigen dir, wie du Next.js-Projekte mit Clean Architecture skalierbar und wartbar hältst.
Jeder kennt es: Ein Projekt startet klein und übersichtlich. Doch nach sechs Monaten, drei neuen Features und zwei API-Wechseln sieht die src/app Struktur aus wie ein Teller Spaghetti. Komponenten enthalten Datenbank-Abfragen, Page-Files sind 500 Zeilen lang und niemand traut sich mehr, eine zentrale Funktion zu ändern. Dieses Phänomen wird oft als "Technical Debt" bezeichnet, aber in Wahrheit ist es ein Mangel an architektonischer Weitsicht.
Clean Architecture ist kein Modewort, sondern eine Überlebensstrategie für Enterprise-Projekte. Es geht darum, eine Struktur zu schaffen, die gegen technische Änderungen (wie den Wechsel von Firebase zu Supabase) immun ist. In diesem Guide schauen wir uns an, wie du Next.js so strukturierst, dass es auch bei 50.000 Zeilen Code noch Spaß macht, daran zu arbeiten.
Die Schichten-Logik (Layers)
Das Hauptprinzip von Clean Architecture, wie es von Robert C. Martin ("Uncle Bob") popularisiert wurde, ist die Abhängigkeits-Regel: Abhängigkeiten dürfen nur von außen nach innen zeigen. Die innerste Schicht (deine Business-Logik) darf niemals wissen, was in der äußeren Schicht (dein Framework oder deine Datenbank) passiert. Das klingt abstrakt, ist aber in der Praxis extrem mächtig.
1. Domain Layer (Der Kern)
Hier liegen deine "Entities" und "Use Cases". Das ist das Herz deiner Anwendung. Wenn du einen Shop baust, ist hier definiert, was ein "Produkt" ist, wie ein Rabatt berechnet wird und was passiert, wenn ein Nutzer etwas in den Warenkorb legt. Dieser Code nutzt keine Frameworks – kein Next.js, kein React, kein Supabase. Nur reines TypeScript. Warum? Damit du deine Logik theoretisch auch in einer React Native App oder einem Node.js Backend nutzen könntest, ohne eine einzige Zeile ändern zu müssen.
2. Application Layer (Die Vermittlung)
Hier liegen die Interfaces (Schnittstellen). Du definierst hier zum Beispiel: "Ich brauche ein ProductRepository, das mir eine Liste von Produkten geben kann." Wie dieses Repository die Daten holt (ob via REST, GraphQL oder Direct Database Access), ist dieser Schicht völlig egal. Sie orchestriert lediglich den Ablauf: "Hol die Produkte vom Repository und wende die Rabatt-Logik aus dem Domain Layer an."
3. Infrastructure Layer (Die Technik)
Hier passiert die "schmutzige" Arbeit. Hier implementierst du das ProductRepository und schreibst den echten supabase.from('products').select() Code. Diese Schicht darf alles wissen: Sie kennt Supabase, sie kennt deine Umgebungsvariablen und sie weiß, wie man Fehler im Netzwerk abfängt. Wenn du später die Datenbank wechselst, änderst du nur diese Schicht. Der Rest der App merkt davon nichts.
Eine saubere Ordnerstruktur für Next.js
Vergiss den riesigen components-Ordner, in dem 50 Dateien unsortiert liegen. In einer professionellen App führt das zu Chaos. Probiere stattdessen einen modularen Ansatz in src/, der sich an Features orientiert:
src/
modules/
auth/
components/ (UI-Komponenten wie LoginButton)
services/ (API-Aufrufe an Supabase Auth)
hooks/ (React-Logik wie useUser)
types/ (TypeScript-Interfaces)
use-cases/ (Business-Logik wie handleSignup)
products/
...
core/
ui/ (Globale Buttons, Inputs, Dialoge)
utils/ (Helper-Funktionen wie formatDate)
api/ (Zentrale API-Konfiguration)
Meine Meinung: Der größte Fehler in Next.js Projekten ist die Vermischung von "Data Fetching" und "UI". Viele Entwickler schreiben ihre SQL-Abfragen direkt in die Client-Komponenten. Das ist der sicherste Weg in den Wartungs-Albtraum. Nutze Server Components, um die Daten in einer page.tsx (Infrastructure/Application Layer) zu holen und reiche sie als "reine Daten" (Props) an deine Komponenten (UI Layer) weiter. Eine Komponente sollte ein "Pure Function" sein: Daten rein, HTML raus.
Dependency Injection: Das Geheimnis der Testbarkeit
Warum machen wir uns die Mühe mit den Interfaces und den Repositories? Wegen der Testbarkeit. Wenn deine Business-Logik gegen ein Interface programmiert ist, kannst du im Test einfach ein "Mock-Repository" einsetzen. Dieses Mock-Repository liefert Daten aus einem lokalen Array statt aus einer echten Datenbank.
Das macht deine Unit-Tests blitzschnell (Millisekunden statt Sekunden) und unabhängig von deiner Internetverbindung oder dem Status deiner Cloud-Provider. Ein Senior-Entwickler erkennt man daran, dass er Code schreibt, der sich einfach testen lässt.
Der "Pragmatic Clean" Ansatz
Ich habe Projekte gesehen, die so "clean" waren, dass man für ein einfaches Textfeld fünf Dateien in vier verschiedenen Ordnern anlegen musste. Das ist das andere Extrem ("Architecture Astronauts").
Die goldene Regel: Sei pragmatisch. Wenn dein Projekt voraussichtlich klein bleibt, nutze die Standard-Struktur von Next.js. Fange erst an zu abstrahieren, wenn du merkst, dass sich Logik an vielen Stellen wiederholt oder wenn die page.tsx Dateien so groß werden, dass du nicht mehr durchblickst. Clean Architecture ist ein Werkzeug, das Probleme lösen soll – es darf keine neuen Probleme durch unnötige Komplexität schaffen.
Fazit: Skalierbarkeit beginnt im Kopf
Clean Architecture in Next.js erfordert Disziplin und ein tiefes Verständnis für die Trennung von Verantwortlichkeiten (Separation of Concerns). Es ist verlockend, "mal schnell" einen API-Call direkt in die Komponente zu schreiben, um Zeit zu sparen. Aber jede dieser Abkürzungen ist eine technische Schuld, die du später mit Zinsen zurückzahlen musst – meistens dann, wenn der Kunde eine Änderung möchte, die eigentlich "ganz einfach" sein sollte, dich aber drei Tage kostet.
Wer Enterprise-Anwendungen baut, muss wie ein Architekt denken, nicht wie ein Maurer. Plane die Schichten, definiere die Schnittstellen und dein zukünftiges Ich (und dein gesamtes Team) wird dir in zwei Jahren danken, wenn das Projekt immer noch sauber, wartbar und erweiterbar ist.
Mehr für Architektur-Liebhaber:
FAQ zu diesem Artikel
d6benjamin
Willkommen auf d6b