Architecture web

Architecture React par fonctionnalités : structurer sans surconcevoir

Othmane Ibn Dahou Idrissi ·

Organisation React en trois niveaux : route, fonctionnalité et composants d’interface partagés.

Un dossier components finit par contenir une carte produit, un formulaire de connexion, une fenêtre de suppression et trois variantes de bouton. Le dossier hooks grossit au même rythme. Chaque modification demande de comprendre plusieurs conventions implicites. Le problème n’est pas forcément la taille du projet : c’est l’absence de frontières qui expliquent à quoi sert chaque morceau de code.

Organiser React par fonctionnalités permet de rapprocher les fichiers qui évoluent ensemble. Cette méthode ne nécessite ni microfrontends ni framework interne. Le scénario utilisé ici est un catalogue fictif avec recherche, favoris et édition administrative. Il sert à choisir une structure proportionnée, pas à imposer une arborescence universelle.

Partir des changements attendus

Avant de déplacer des dossiers, décrivez trois évolutions plausibles : ajouter un filtre au catalogue, changer le fournisseur des produits et modifier les règles d’édition. Si chaque évolution traverse les mêmes fichiers sans raison claire, les responsabilités sont probablement mélangées.

Une fonctionnalité représente un comportement compréhensible par l’équipe : consulter le catalogue, gérer ses favoris, modifier un produit. Un bouton visuel n’est pas une fonctionnalité métier. À l’inverse, appeler « composant » un fichier qui charge des données, vérifie les droits, trie une liste et enregistre un formulaire ne rend pas son rôle simple.

La méthode Thinking in React invite à raisonner à partir de l’interface, de sa décomposition et de l’état nécessaire. Pour l’architecture, on peut compléter ce raisonnement par une question : quelles décisions doivent pouvoir changer indépendamment ? Une API et un style de carte ne devraient pas être liés par accident.

Une arborescence de départ lisible

Pour une application modeste, cette organisation suffit souvent. Les noms sont illustratifs ; adaptez-les au vocabulaire du produit plutôt qu’à une mode d’architecture.

src/
  app/
    catalogue/page.tsx
    favoris/page.tsx
  features/
    catalogue/
      model.ts
      search-products.ts
      product-card.tsx
      product-grid.tsx
      product-repository.server.ts
    favoris/
      favorite-button.tsx
      favorites-store.ts
  components/
    ui/
      button.tsx
      dialog.tsx
  lib/
    http.ts

Le dossier app compose les routes et respecte les conventions du framework. features/catalogue porte les concepts propres au catalogue. components/ui contient des primitives visuelles suffisamment stables et réellement partagées. lib/http.ts peut regrouper un comportement réseau transversal ; il ne doit pas devenir un entrepôt de règles produit sans propriétaire.

Ne créez pas systématiquement cinq sous-dossiers dans chaque fonctionnalité. Trois fichiers lisibles valent mieux qu’une arborescence vide conçue pour une croissance hypothétique. Vous pourrez introduire components, queries ou tests à l’intérieur lorsque le volume le justifiera.

Séparer le format externe du modèle utilisé par l’interface

Une API peut retourner product_name, un prix en centimes et des propriétés internes. Si les composants consomment directement cette réponse partout, tout changement de fournisseur se diffuse dans l’interface. Un adaptateur à l’entrée permet de définir un contrat plus petit.

export type Product = {
  id: string;
  name: string;
  priceCents: number;
};

type ApiProduct = {
  id: string;
  product_name: string;
  price_cents: number;
};

export function toProduct(input: ApiProduct): Product {
  return {
    id: input.id,
    name: input.product_name,
    priceCents: input.price_cents,
  };
}

Cet exemple décrit une transformation, pas une validation réseau. Une réponse JSON reste inconnue à l’exécution ; il faut vérifier son schéma avant d’appeler l’adaptateur. Le type TypeScript n’empêche pas un serveur distant de renvoyer null ou une valeur négative là où elle n’a pas de sens métier.

L’adaptateur est utile lorsque les formats diffèrent réellement. Copier mécaniquement un objet identique dans plusieurs couches ne crée pas de protection supplémentaire. On peut commencer avec un contrat simple, puis extraire une transformation au moment où une dépendance externe devient visible.

Placer chaque état près de son usage

Une ouverture de menu appartient généralement au menu. Un filtre partageable peut vivre dans l’URL. Une liste de produits venant du serveur n’a pas forcément besoin d’être recopiée dans un état global. La documentation React sur la structure de l’état souligne les difficultés des données redondantes et contradictoires.

Dans notre catalogue, la liste filtrée peut être dérivée des produits et de la recherche. Stocker à la fois les produits, la recherche, la liste filtrée et son nombre introduit plusieurs valeurs à synchroniser. Commencez par calculer les deux dernières ; optimisez ensuite si une mesure montre un coût réel.

Les favoris constituent un autre cas : ils doivent peut-être être partagés entre plusieurs cartes et une page dédiée. Cette portée justifie un stockage commun. Il faut alors préciser sa source : navigateur pour une préférence locale, serveur pour une sélection attachée au compte. Mélanger ces deux promesses produit des pertes de données difficiles à expliquer.

Formaliser les dépendances autorisées

Une règle simple est que la page peut composer plusieurs fonctionnalités, tandis qu’une primitive UI ne connaît pas les règles du catalogue. Si button.tsx importe un service de produits, la dépendance remonte dans le mauvais sens. Si deux fonctionnalités s’importent mutuellement, cherchez le contrat commun ou remontez leur orchestration dans un parent.

Dans Next.js, ajoutez une deuxième frontière : les modules serveur qui accèdent à des secrets ne doivent pas rejoindre le graphe client. Le suffixe .server.ts exprime une intention, mais ce nom seul ne constitue pas une protection. Utilisez les mécanismes du framework et vérifiez les imports. Le guide Server Components et use client détaille ce point.

Un fichier index.ts qui réexporte tout peut masquer ces dépendances. Il devient particulièrement risqué s’il mélange modules client et serveur. Préférez des imports explicites tant que la surface publique d’une fonctionnalité n’est pas suffisamment stable pour justifier une façade.

Tester les règles qui peuvent vraiment casser

Un test utile vérifie une règle de recherche, un contrat de données ou un refus d’écriture. Il ne se limite pas à reproduire la structure des fichiers. Pour un filtre, testez les accents, une recherche vide et les valeurs manquantes selon les exigences réelles. Pour une édition, testez le refus serveur même si le bouton est masqué côté client.

Les tests de composants doivent se concentrer sur le comportement observable : un filtre modifie les résultats, une erreur conserve les valeurs, un dialogue rend le focus à son déclencheur. Le guide des formulaires React accessibles fournit plusieurs scénarios de ce type.

Gardez quelques parcours complets pour les frontières critiques : chargement, modification, confirmation et relecture. Ils détectent les erreurs d’intégration que les fonctions isolées ne voient pas. Évitez toutefois de transformer chaque variation visuelle en test lourd ; le coût de maintenance doit rester proportionné au risque.

Migrer progressivement sans interrompre les évolutions

Choisissez une fonctionnalité qui doit déjà être modifiée. Cartographiez ses imports, rapprochez ses fichiers et introduisez uniquement les contrats nécessaires. Faites un premier changement structurel sans modification de comportement, puis ajoutez l’évolution produit. Cette séparation facilite la revue et le diagnostic d’une régression.

Mesurez la réussite avec des questions concrètes : peut-on identifier le responsable d’une règle, changer une source sans toucher dix composants, tester une erreur sans lancer toute l’application ? Le nombre de dossiers et l’usage d’un vocabulaire architectural ne prouvent rien à eux seuls.

Documentez les décisions inhabituelles dans un court fichier de contribution. Expliquez pourquoi une dépendance est interdite, avec un exemple du projet. Une convention comprise par deux développeurs vaut mieux qu’un schéma ambitieux que personne ne suit pendant une correction urgente.

Questions fréquentes

Faut-il adopter une architecture hexagonale complète ?

Seulement si ses séparations répondent à des changements et des risques réels. Une petite interface de contenu peut se contenter de fonctionnalités, de modules serveur explicites et de composants UI partagés. Ajoutez des couches lorsqu’elles réduisent une dépendance concrète.

Quand extraire un composant partagé ?

Quand plusieurs usages partagent le même contrat et la même intention. Deux blocs qui se ressemblent aujourd’hui peuvent évoluer différemment. Une abstraction avec de nombreux booléens est souvent le signe que des comportements distincts ont été réunis trop tôt.

Cette organisation rend-elle l’application plus rapide ?

Pas directement. Elle facilite l’identification des dépendances et du travail inutile, mais les gains doivent être mesurés. Le guide React et INP traite cette étape. Les projets présentés sur le portfolio donnent le contexte de mon activité, sans transformer ces recommandations en résultats chiffrés non vérifiés.

ReactTypeScriptArchitectureMaintenabilité