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 dienen der Organisation Ihres Anwendungscodes und statischer Assets.

Top-Level-Dateien

Top-Level-Dateien werden zur Konfiguration Ihrer Anwendung, Verwaltung von Abhängigkeiten, Ausführung von Middleware, Integration von Monitoring-Tools und Definition von Umgebungsvariablen verwendet.

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 in Bezug auf die Organisation und Zusammenstellung Ihrer Projektdateien. 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 ihres übergeordneten Segments verschachtelt werden.

Colocation (Zusammenlagerung)

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 zusammen innerhalb von Routensegmenten im app-Verzeichnis abgelegt werden können, ohne versehentlich routbar zu sein.

Gut zu wissen: Während Sie Ihre Projektdateien in app zusammenlegen können, müssen Sie dies nicht tun. 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: _folderName

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

Da Dateien im app-Verzeichnis standardmäßig sicher zusammengelegt werden können, sind private Ordner für die Zusammenlagerung 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 es keine Framework-Konvention ist, können Sie auch Dateien außerhalb privater Ordner als "privat" markieren, indem Sie das gleiche Unterstrichmuster 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: (folderName)

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. Marketingseiten, Admin-Seiten usw.
• Ermöglichen verschachtelter Layouts auf demselben Routensegment-Level:
  • Erstellen mehrerer verschachtelter Layouts im selben 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 den Anwendungscode von Projektkonfigurationsdateien, die meist im Stammverzeichnis eines Projekts liegen.

Beispiele

Der folgende Abschnitt gibt einen sehr hochrangigen Überblick über gängige 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. Ihre 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 Funktion oder Route aufteilen

Diese Strategie speichert global geteilten Anwendungscode im Stammverzeichnis von app und teilt spezifischeren Anwendungscode in die Routensegmente auf, die ihn 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 die 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 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-Skelett ü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 Ihre 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 zu unterteilen, die eine komplett andere UI oder Erfahrung haben. 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.