Comment je structure une grande application React

De nombreuses applications React commencent avec une structure de ce type :

src/
|-- components/
|-- hooks/
|-- services/
|-- types/
|-- utils/
`-- pages/

Elle paraît organisée parce que chaque fichier appartient à une catégorie technique. Le problème est que ces catégories ne disent rien sur la responsabilité fonctionnelle.

Un tableau d’historique des commandes, une boîte de dialogue de paiement et la navigation principale sont tous des composants. Une fonction de formatage monétaire, une vérification d’autorisation et un calcul de paiement peuvent tous être qualifiés d’utilitaires. Un hook de récupération de données et un hook de raccourci clavier restent tous deux des hooks, alors qu’ils appartiennent à des parties complètement différentes du produit.

À mesure que l’application grandit, ces dossiers présentent des modes d’échec prévisibles :

• Les développeurs doivent chercher dans plusieurs répertoires globaux pour comprendre une seule fonctionnalité.
• Des noms similaires s’accumulent parce que le dossier ne fournit plus de contexte métier.
• Des détails d’implémentation privés deviennent des imports pratiques pour des fonctionnalités sans rapport.
• Des modifications qui devraient rester locales exigent d’intervenir dans `components`, `hooks`, `services`, `types` et `utils`.
• Personne ne sait plus ce qui est véritablement partagé et ce qui a simplement atterri dans un emplacement partagé.
• Des dépendances circulaires apparaissent faute de direction de dépendance explicite.

Le problème ne vient pas des noms `components`, `hooks` ou `utils`. J’utilise toujours ces dossiers à l’intérieur d’un module bien délimité. Le problème consiste à faire du type technique le premier principe d’organisation.

À l’échelle de l’application, j’organise le code selon sa responsabilité et sa raison de changer.

Une fonctionnalité est un comportement qu’un utilisateur ou un autre système peut déclencher : annuler une commande, inviter un membre dans une équipe, modifier un moyen de paiement ou exporter un rapport. Je préfère les noms qui décrivent une capacité aux périmètres vagues tels que `dashboard` ou `common`.

Un module fonctionnel peut prendre en charge :

• Les composants React utilisés pour exécuter cette capacité.
• Les hooks et l’état d’interaction propres à la fonctionnalité.
• La validation et la transformation des données de formulaire.
• Les opérations API utilisées uniquement par la fonctionnalité.
• La coordination entre les règles métier et l’infrastructure.
• Les tests qui protègent le comportement de la fonctionnalité.

Les fichiers qui changent ensemble restent ainsi proches les uns des autres. Un développeur qui travaille sur l’annulation d’une commande ne devrait pas devoir parcourir six dossiers globaux pour retracer une seule interaction.

Une organisation par fonctionnalités ne signifie pas qu’il faut placer tout ce qui concerne les commandes dans un énorme dossier `orders`. Un domaine est un concept métier. Une fonctionnalité est une opération qui implique ce concept. Cette distinction empêche un grand module de domaine de devenir le prochain fourre-tout.

La couche de routage ou la couche applicative assemble les fonctionnalités. Une fonctionnalité ne doit pas fouiller dans les fichiers internes d’une autre pour lui emprunter un hook ou un composant. Si deux fonctionnalités ont besoin de la même règle métier, celle-ci appartient probablement à un module de domaine. Si elles ont besoin de la même primitive technique, celle-ci appartient probablement à `shared`.

Je sépare les mécanismes de transport des opérations du produit.

La couche API partagée peut prendre en charge l’URL de base, les en-têtes d’authentification, l’annulation des requêtes, la normalisation des erreurs, les en-têtes de traçage et l’analyse du JSON. Elle ne doit pas savoir comment annuler une commande ou inviter un membre.

L’adaptateur de la fonctionnalité ou du domaine concerné possède les chemins des endpoints, les DTO de requête et de réponse, ainsi que la conversion des données de transport en types applicatifs.

import { httpClient } from "@/shared/api";

type CancelOrderResponseDto = {
  order_id: string;
  status: "cancelled";
  cancelled_at: string;
};

export async function cancelOrder(orderId: string) {
  const response = await httpClient.post<CancelOrderResponseDto>(
    `/orders/${orderId}/cancellation`,
  );

  return {
    orderId: response.order_id,
    status: response.status,
    cancelledAt: new Date(response.cancelled_at),
  };
}

Cette frontière empêche les formats d’échange de se répandre dans les composants et les règles métier. Si le backend renomme un champ ou renvoie une nouvelle représentation, la modification est absorbée à l’endroit où le contrat externe entre dans le module.

J’évite un fichier global `api.ts` ou `services.ts` qui contiendrait tous les endpoints. De tels fichiers centralisent des sources de changement sans rapport entre elles. Ils semblent pratiques jusqu’à ce que chaque équipe doive modifier le même module et que chaque consommateur puisse importer n’importe quelle opération.

Le modèle de dépendances reste volontairement simple :

app  ----> features ----> domains
 |           |              |
 +-----------+--------------> shared

• La couche `app` peut assembler les fonctionnalités, les domaines et les primitives partagées.
• Les fonctionnalités peuvent dépendre des modules de domaine et de l’infrastructure partagée.
• Les domaines peuvent dépendre de petites primitives partagées et stables, mais pas des fonctionnalités ni de `app`.
• `shared` ne doit dépendre ni des fonctionnalités du produit ni des domaines.
• Une fonctionnalité ne doit pas importer l’implémentation privée d’une autre fonctionnalité.

Lorsque deux fonctionnalités doivent se coordonner, je les assemble dans la couche applicative ou j’extrais le comportement métier stable qu’elles partagent. Je ne résous pas le problème par un import relatif profond.

Ces règles doivent pouvoir être appliquées automatiquement. Les alias de chemins améliorent la lisibilité, mais ils ne créent pas de frontières. Dans une grande équipe, j’ajoute des règles de lint limitant les imports, un outil de contrôle des frontières de modules ou des exports de packages, afin qu’un import invalide échoue avant la revue de code. Dans un monorepo, les mêmes règles peuvent s’exprimer sous forme de dépendances entre packages.

Il existe des exceptions légitimes. Une règle de frontière doit rendre visible un couplage inhabituel, pas obliger les développeurs à construire des contournements élaborés. Lorsque j’autorise une exception, je consigne pourquoi la dépendance existe, qui en est responsable et ce qui permettrait de la supprimer plus tard.

J’organise les tests selon leur responsabilité, pas selon le vocabulaire d’une bibliothèque de test.

src/
|-- domains/orders/tests/
|   `-- can-cancel-order.test.ts
|-- features/cancel-order/tests/
|   |-- cancel-order-contract.test.ts
|   `-- cancel-order-dialog.test.tsx
`-- shared/testing/
    |-- render-application.tsx
    |-- factories/
    `-- server/

e2e/
`-- cancel-order.spec.ts

Les tests de logique métier pure restent avec le domaine. Les tests de comportement et de contrat d’une fonctionnalité restent avec celle-ci. Le dossier de test partagé contient l’infrastructure utilisée par de nombreux modules : fonctions d’enveloppe de rendu, fabriques de données, constructeurs déterministes et gestionnaires réseau. Il ne doit pas devenir un deuxième dossier `utils` rempli de données de test propres à certains besoins métier.

Les tests de bout en bout se trouvent à la racine du dépôt parce qu’ils exercent des parcours utilisateur déployés qui traversent les frontières des modules. Leur emplacement reflète la portée du test, pas une préférence pour un outil d’exécution particulier.

Une arborescence de premier niveau divisée en tests unitaires, d’intégration et de composants recrée généralement le même problème de navigation que `components`, `hooks` et `utils`. Ces étiquettes décrivent la manière dont un test s’exécute. Elles ne disent pas qui est responsable du comportement lorsqu’il échoue.

Je n’interromprais pas la livraison pour réorganiser une application existante selon cette arborescence. Les grandes restructurations génèrent beaucoup de remaniements sans démontrer que les nouvelles frontières sont meilleures.

Je choisis plutôt une tranche verticale significative. Je place ses composants d’interface, sa logique d’interaction, son adaptateur API et ses règles métier derrière l’API publique d’une fonctionnalité. Je corrige le sens des dépendances autour de cette tranche, puis j’utilise la fonctionnalité suivante pour vérifier que le modèle tient toujours.

La structure justifie sa place lorsque les modifications courantes deviennent plus locales, que le code privé le reste et que les développeurs peuvent expliquer pourquoi une dépendance est autorisée. Si une frontière résiste constamment au produit, je la change. La cohérence est précieuse, mais protéger la mauvaise abstraction ne l’est pas.