Structure et organisation de projet

Cette page fournit un aperçu de toutes les conventions de dossiers et fichiers dans Next.js, ainsi que des recommandations pour organiser votre projet.

Conventions de dossiers et fichiers

Dossiers de premier niveau

Les dossiers de premier niveau sont utilisés pour organiser le code de votre application et les ressources statiques.

Fichiers de premier niveau

Les fichiers de premier niveau sont utilisés pour configurer votre application, gérer les dépendances, exécuter des middlewares, intégrer des outils de surveillance et définir des variables d'environnement.

Fichiers de routage

Routes imbriquées

Routes dynamiques

Groupes de routes et dossiers privés

Routes parallèles et interceptées

Conventions de fichiers de métadonnées

Icônes d'application

Images Open Graph et Twitter

SEO

Organisation de votre projet

Next.js est non opinionated sur la façon dont vous organisez et colocalisez les fichiers de votre projet. Mais il fournit plusieurs fonctionnalités pour vous aider à organiser votre projet.

Hiérarchie des composants

Les composants définis dans des fichiers spéciaux sont rendus dans une hiérarchie spécifique :

• layout.js
• template.js
• error.js (limite d'erreur React)
• loading.js (limite de suspense React)
• not-found.js (limite d'erreur React)
• page.js ou layout.js imbriqué

Les composants sont rendus de manière récursive dans les routes imbriquées, ce qui signifie que les composants d'un segment de route seront imbriqués à l'intérieur des composants de son segment parent.

Colocalisation

Dans le répertoire app, les dossiers imbriqués définissent la structure des routes. Chaque dossier représente un segment de route qui est mappé à un segment correspondant dans un chemin URL.

Cependant, même si la structure des routes est définie par des dossiers, une route n'est pas accessible publiquement tant qu'un fichier page.js ou route.js n'est pas ajouté à un segment de route.

Et, même lorsqu'une route est rendue accessible publiquement, seul le contenu renvoyé par page.js ou route.js est envoyé au client.

Cela signifie que les fichiers du projet peuvent être colocalisés en toute sécurité à l'intérieur des segments de route dans le répertoire app sans devenir accidentellement accessibles.

Bon à savoir : Bien que vous puissiez colocaliser vos fichiers projet dans app, vous n'êtes pas obligé. Si vous préférez, vous pouvez les conserver en dehors du répertoire app.

Dossiers privés

Les dossiers privés peuvent être créés en préfixant un dossier avec un tiret bas : _nomDossier

Cela indique que le dossier est un détail d'implémentation privé et ne doit pas être pris en compte par le système de routage, excluant ainsi le dossier et tous ses sous-dossiers du routage.

Comme les fichiers dans le répertoire app peuvent être colocalisés en toute sécurité par défaut, les dossiers privés ne sont pas nécessaires pour la colocalisation. Cependant, ils peuvent être utiles pour :

• Séparer la logique d'interface utilisateur de la logique de routage.
• Organiser de manière cohérente les fichiers internes dans un projet et l'écosystème Next.js.
• Trier et regrouper les fichiers dans les éditeurs de code.
• Éviter les conflits de noms potentiels avec les futures conventions de fichiers Next.js.

Bon à savoir :

• Bien que ce ne soit pas une convention du framework, vous pourriez aussi envisager de marquer les fichiers en dehors des dossiers privés comme "privés" en utilisant le même motif de tiret bas.
• Vous pouvez créer des segments URL commençant par un tiret bas en préfixant le nom du dossier avec %5F (la forme encodée URL d'un tiret bas) : %5FnomDossier.
• Si vous n'utilisez pas de dossiers privés, il serait utile de connaître les conventions de fichiers spéciales de Next.js pour éviter des conflits de noms inattendus.

Groupes de routes

Les groupes de routes peuvent être créés en entourant un dossier de parenthèses : (nomDossier)

Cela indique que le dossier est à des fins d'organisation et ne doit pas être inclus dans le chemin URL de la route.

Les groupes de routes sont utiles pour :

• Organiser les routes par section de site, intention ou équipe. Par exemple, pages marketing, pages admin, etc.
• Permettre des mises en page imbriquées au même niveau de segment de route :
  • Créer plusieurs mises en page imbriquées dans le même segment, y compris plusieurs mises en page racine
  • Ajouter une mise en page à un sous-ensemble de routes dans un segment commun

Dossier src

Next.js prend en charge le stockage du code d'application (y compris app) dans un dossier src optionnel. Cela sépare le code d'application des fichiers de configuration du projet qui se trouvent principalement à la racine d'un projet.

Exemples

La section suivante présente un aperçu très général des stratégies courantes. Le principal conseil est de choisir une stratégie qui fonctionne pour vous et votre équipe et de rester cohérent dans tout le projet.

Bon à savoir : Dans nos exemples ci-dessous, nous utilisons les dossiers components et lib comme placeholders génériques ; leur nom n'a aucune signification particulière dans le framework et vos projets pourraient utiliser d'autres dossiers comme ui, utils, hooks, styles, etc.

Stocker les fichiers projet en dehors de app

Cette stratégie stocke tout le code d'application dans des dossiers partagés à la racine de votre projet et garde le répertoire app uniquement pour les besoins de routage.

Stocker les fichiers projet dans des dossiers de premier niveau à l'intérieur de app

Cette stratégie stocke tout le code d'application dans des dossiers partagés à la racine du répertoire app.

Diviser les fichiers projet par fonctionnalité ou route

Cette stratégie stocke le code d'application partagé globalement dans le répertoire racine app et divise le code d'application plus spécifique dans les segments de route qui les utilisent.

Organiser les routes sans affecter le chemin URL

Pour organiser les routes sans affecter l'URL, créez un groupe pour garder les routes associées ensemble. Les dossiers entre parenthèses seront omis de l'URL (par exemple (marketing) ou (shop)).

Même si les routes à l'intérieur de (marketing) et (shop) partagent la même hiérarchie URL, vous pouvez créer une mise en page différente pour chaque groupe en ajoutant un fichier layout.js dans leurs dossiers.

Inclure des segments spécifiques dans une mise en page

Pour inclure des routes spécifiques dans une mise en page, créez un nouveau groupe de routes (par exemple (shop)) et déplacez les routes qui partagent la même mise en page dans le groupe (par exemple account et cart). Les routes en dehors du groupe ne partageront pas la mise en page (par exemple checkout).

Opter pour des squelettes de chargement sur une route spécifique

Pour appliquer un squelette de chargement via un fichier loading.js à une route spécifique, créez un nouveau groupe de routes (par exemple /(overview)) puis placez votre loading.tsx à l'intérieur de ce groupe de routes.

Maintenant, le fichier loading.tsx ne s'appliquera qu'à votre page dashboard → overview au lieu de toutes vos pages dashboard, sans affecter la structure du chemin URL.

Créer plusieurs mises en page racine

Pour créer plusieurs mises en page racine, supprimez le fichier layout.js de premier niveau et ajoutez un fichier layout.js dans chaque groupe de routes. C'est utile pour partitionner une application en sections ayant une interface ou une expérience complètement différente. Les balises <html> et <body> doivent être ajoutées à chaque mise en page racine.

Dans l'exemple ci-dessus, (marketing) et (shop) ont chacun leur propre mise en page racine.