Structure et organisation du 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 et les ressources statiques de votre application.

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 les 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 d'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 conenu renvoyé par page.js ou route.js est envoyé au client.

Cela signifie que les fichiers du projet peuvent être sécurisés par colocalisation à l'intérieur des segments de route dans le répertoire app sans risquer d'être accessibles par erreur.

Bon à savoir : Bien que vous puissiez colocaliser vos fichiers de 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 : _nomDuDossier

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 sécurisés par colocalisation 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 également 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 d'URL commençant par un tiret bas en préfixant le nom du dossier avec %5F (la forme encodée d'un tiret bas) : %5FnomDuDossier.
• 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 : (nomDuDossier)

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

Les groupes de routes sont utiles pour :

• Organiser les routes par section du 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 de l'application (y compris app) dans un dossier src optionnel. Cela sépare le code de l'application des fichiers de configuration du projet qui se trouvent principalement à la racine d'un projet.

Exemples

La section suivante présente une vue d'ensemble très générale 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 pas de signification particulière dans le framework et vos projets pourraient utiliser d'autres dossiers comme ui, utils, hooks, styles, etc.

Stocker les fichiers de projet en dehors de app

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

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

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

Diviser les fichiers de projet par fonctionnalité ou route

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

Organiser les routes sans affecter le chemin d'URL

Pour organiser les routes sans affecter l'URL, créez un groupe pour garder les routes lié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 d'URL, vous pouvez créer une mise en page différente pour chaque groupe en ajoutant un fichier layout.js dans leurs dossiers.

Opter pour une mise en page sur des segments spécifiques

Pour opter pour une mise en page sur des routes spécifiques, 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 d'URL.

Créer plusieurs mises en page racine

Pour créer plusieurs mises en page racine, supprimez le fichier layout.js de niveau supérieur et ajoutez un fichier layout.js dans chaque groupe de routes. Cela 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.