Projektstruktur und Organisation

Diese Seite bietet einen Überblick über alle Ordner- und Dateikonventionen in Next.js sowie Empfehlungen zur Organisation Ihres Projekts.

Ordner- und Dateikonventionen

Top-Level-Ordner

Top-Level-Ordner werden verwendet, um den Code Ihrer Anwendung und statische Assets zu organisieren.

Top-Level-Dateien

Top-Level-Dateien werden verwendet, um Ihre Anwendung zu konfigurieren, Abhängigkeiten zu verwalten, Middleware auszuführen, Monitoring-Tools zu integrieren und Umgebungsvariablen zu definieren.

Routing-Dateien

Verschachtelte Routen

Dynamische Routen

Routengruppen und private Ordner

Parallele und abgefangene Routen

Metadaten-Dateikonventionen

App-Icons

Open Graph- und Twitter-Bilder

SEO

Organisation Ihres Projekts

Next.js ist nicht vorschreibend darüber, wie Sie Ihre Projektdateien organisieren und zusammenstellen. Es bietet jedoch mehrere Funktionen, die Ihnen bei der Organisation Ihres Projekts helfen.

Komponentenhierarchie

Die in speziellen Dateien definierten Komponenten werden in einer bestimmten Hierarchie gerendert:

• layout.js
• template.js
• error.js (React-Fehlerbegrenzung)
• loading.js (React-Suspense-Begrenzung)
• not-found.js (React-Fehlerbegrenzung)
• page.js oder verschachteltes layout.js

Die Komponenten werden rekursiv in verschachtelten Routen gerendert, was bedeutet, dass die Komponenten eines Routensegments innerhalb der Komponenten seines übergeordneten Segments verschachtelt werden.

Colocation

Im app-Verzeichnis definieren verschachtelte Ordner die Routenstruktur. Jeder Ordner repräsentiert ein Routensegment, das einem entsprechenden Segment in einem URL-Pfad zugeordnet ist.

Allerdings ist eine Route nicht öffentlich zugänglich, bis eine page.js- oder route.js-Datei zu einem Routensegment hinzugefügt wird.

Und selbst wenn eine Route öffentlich zugänglich gemacht wird, wird nur der Inhalt, der von page.js oder route.js zurückgegeben wird, an den Client gesendet.

Das bedeutet, dass Projektdateien sicher im gleichen Ordner innerhalb von Routensegmenten im app-Verzeichnis platziert werden können, ohne versehentlich routbar zu sein.

Gut zu wissen: Während Sie Ihre Projektdateien in app colokalisieren können, müssen Sie das nicht. Wenn Sie es bevorzugen, können Sie sie außerhalb des app-Verzeichnisses belassen.

Private Ordner

Private Ordner können erstellt werden, indem einem Ordner ein Unterstrich vorangestellt wird: _ordnerName

Dies zeigt an, dass der Ordner ein privates Implementierungsdetail ist und nicht vom Routing-System berücksichtigt werden sollte, wodurch der Ordner und alle seine Unterordner vom Routing ausgenommen werden.

Da Dateien im app-Verzeichnis standardmäßig sicher colokalisiert werden können, sind private Ordner für die Colokalisierung nicht erforderlich. Sie können jedoch nützlich sein für:

• Trennung von UI-Logik und Routing-Logik.
• Konsistente Organisation interner Dateien in einem Projekt und im Next.js-Ökosystem.
• Sortierung und Gruppierung von Dateien in Code-Editoren.
• Vermeidung potenzieller Namenskonflikte mit zukünftigen Next.js-Dateikonventionen.

Gut zu wissen:

• Obwohl keine Framework-Konvention, können Sie auch Dateien außerhalb privater Ordner als "privat" markieren, indem Sie das gleiche Unterstrich-Muster verwenden.
• Sie können URL-Segmente erstellen, die mit einem Unterstrich beginnen, indem Sie dem Ordnernamen %5F voranstellen (die URL-kodierte Form eines Unterstrichs): %5FfolderName.
• Wenn Sie keine privaten Ordner verwenden, ist es hilfreich, die speziellen Dateikonventionen von Next.js zu kennen, um unerwartete Namenskonflikte zu vermeiden.

Routengruppen

Routengruppen können erstellt werden, indem ein Ordner in Klammern eingeschlossen wird: (ordnerName)

Dies zeigt an, dass der Ordner nur organisatorischen Zwecken dient und nicht in den URL-Pfad der Route aufgenommen werden sollte.

Routengruppen sind nützlich für:

• Organisation von Routen nach Website-Bereich, Absicht oder Team, z.B. Marketing-Seiten, Admin-Seiten usw.
• Ermöglichen verschachtelter Layouts auf demselben Routensegment-Level:
  • Erstellen mehrerer verschachtelter Layouts im gleichen Segment, einschließlich mehrerer Root-Layouts
  • Hinzufügen eines Layouts zu einer Teilmenge von Routen in einem gemeinsamen Segment

src-Ordner

Next.js unterstützt die Speicherung von Anwendungscode (einschließlich app) in einem optionalen src-Ordner. Dies trennt Anwendungscode von Projektkonfigurationsdateien, die meist im Stammverzeichnis eines Projekts liegen.

Beispiele

Der folgende Abschnitt listet eine sehr hochrangige Übersicht gängiger Strategien. Die einfachste Erkenntnis ist, eine Strategie zu wählen, die für Sie und Ihr Team funktioniert, und diese konsistent im Projekt anzuwenden.

Gut zu wissen: In unseren Beispielen unten verwenden wir components- und lib-Ordner als allgemeine Platzhalter. Deren Benennung hat keine besondere Bedeutung für das Framework, und Ihre Projekte könnten andere Ordner wie ui, utils, hooks, styles usw. verwenden.

Projektdateien außerhalb von app speichern

Diese Strategie speichert den gesamten Anwendungscode in gemeinsamen Ordnern im Stammverzeichnis Ihres Projekts und behält das app-Verzeichnis rein für Routing-Zwecke bei.

Projektdateien in Top-Level-Ordnern innerhalb von app speichern

Diese Strategie speichert den gesamten Anwendungscode in gemeinsamen Ordnern im Stammverzeichnis des app-Verzeichnisses.

Projektdateien nach Feature oder Route aufteilen

Diese Strategie speichert global geteilten Anwendungscode im Stammverzeichnis des app-Verzeichnisses und teilt spezifischeren Anwendungscode in die Routensegmente auf, die sie verwenden.

Routen organisieren, ohne den URL-Pfad zu beeinflussen

Um Routen zu organisieren, ohne die URL zu beeinflussen, erstellen Sie eine Gruppe, um verwandte Routen zusammenzuhalten. Die Ordner in Klammern werden aus der URL ausgelassen (z.B. (marketing) oder (shop)).

Obwohl Routen innerhalb von (marketing) und (shop) die gleiche URL-Hierarchie teilen, können Sie für jede Gruppe ein unterschiedliches Layout erstellen, indem Sie eine layout.js-Datei in ihren Ordnern hinzufügen.

Bestimmte Segmente für ein Layout auswählen

Um bestimmte Routen für ein Layout auszuwählen, erstellen Sie eine neue Routengruppe (z.B. (shop)) und verschieben Sie die Routen, die das gleiche Layout teilen, in die Gruppe (z.B. account und cart). Die Routen außerhalb der Gruppe teilen das Layout nicht (z.B. checkout).

Lade-Skelette für eine bestimmte Route auswählen

Um ein Lade-Skeleton über eine loading.js-Datei auf eine bestimmte Route anzuwenden, erstellen Sie eine neue Routengruppe (z.B. /(overview)) und verschieben Sie Ihre loading.tsx in diese Routengruppe.

Nun wird die loading.tsx-Datei nur auf Ihre Dashboard → Übersichtsseite angewendet, anstatt auf alle Dashboard-Seiten, ohne die URL-Pfadstruktur zu beeinflussen.

Mehrere Root-Layouts erstellen

Um mehrere Root-Layouts zu erstellen, entfernen Sie die layout.js-Datei auf oberster Ebene und fügen Sie eine layout.js-Datei in jede Routengruppe ein. Dies ist nützlich, um eine Anwendung in Abschnitte mit völlig unterschiedlicher UI oder Benutzererfahrung aufzuteilen. Die <html>- und <body>-Tags müssen zu jedem Root-Layout hinzugefügt werden.

Im obigen Beispiel haben sowohl (marketing) als auch (shop) ihr eigenes Root-Layout.