La structure d'un projet (7) : le bouton qui a bougé sur deux écrans
Par Dorian Chávez · cofondateur et Chief Executive Officer de Hábil ·
Un écran React avec TypeScript et Vite, découpé par fonctionnalité : où vit chaque fichier, ce qu'arrête ESLint et ce que nous avons mesuré sur le modèle.
La structure d'un projet · épisode 7 sur 7 · React
Scénario : les personnages et l'histoire sont inventés. Les données techniques et les citations ont leur source à la fin.
En 1 minute
- Le restaurant des épisodes 5 et 6 avait une cuisine. Voici la salle : ce que voit le client. Les règles sont les mêmes (chacun à sa place, les flèches dans un seul sens) ; ce qui change, c'est la façon de découper le projet.
- Côté backend, on découpe par couches : serveur, cuisinier, garde-manger. À l'écran, on découpe par fonctionnalité : « passer une commande » et « voir ma commande » vivent chacune dans son dossier, avec tout ce qui lui appartient à l'intérieur.
- La règle qui en décide : un fichier vit là où on le supprimerait. Si demain la boutique cesse de vendre sur le web, tu supprimes un dossier et sa page, et rien d'autre ne casse.
- Une fonctionnalité n'importe pas les pièces d'une autre. TypeScript et Vite ne le voient pas : ça compile, ça se construit et ça passe les tests. Dans le modèle, c'est ESLint qui l'arrête, et un script démontre qu'il l'arrête.
- Mesuré sur le modèle : 37 tests au vert, lus dans le rapport ; chaque écran voyage dans son propre morceau de code (chunk), de 3 kB, et le contrat avec l'API de l'épisode 6 a été testé en direct.
- Pour lundi : cherche dans ton projet un composant importé depuis deux dossiers de fonctionnalité différents. C'est le bouton qui va bouger sur deux écrans.
Dans cet article
- Que s'est-il passé vendredi à 17:40 ?
- Qu'est-ce qui change, et qu'est-ce qui ne change pas ?
- Où vit chaque fichier ?
- Qu'est-ce qui va dans chaque dossier ?
- Qui surveille les frontières ?
- Qu'avons-nous mesuré ?
- Quelles sont cinq erreurs fréquentes ?
- Exercice : peux-tu mettre le formulaire sur l'écran du ticket ?
- À retenir
- Ce que laissent les sept épisodes
- Le modèle et le cours
- Que fait Hábil ?
- Références
Que s'est-il passé vendredi à 17:40 ?
Iván a déplacé un bouton sur l'écran du ticket. Lundi, le bouton avait aussi bougé sur l'écran de paiement.
Vendredi, 17:40. Troisième étage.
La demande était petite. La boutique voulait le bouton « Imprimer le ticket » en haut, à côté du numéro de la commande, et non tout en bas, où personne ne le voyait. Iván a ouvert le dossier src/ du projet React et a trouvé quatre-vingts fichiers au même niveau : Ticket.tsx, Boton.tsx, api.ts, utils.ts, PaginaPago.tsx, useDatos.ts. Aucun dossier ne disait à qui appartenait chaque chose.
Il a cherché le bouton et l'a trouvé dans Ticket.tsx. Il l'a remonté de trois lignes. Il a lancé les commandes habituelles :
$ npx tsc -b
$ npm run build
✓ built in 412ms
$ npm test
Tests 12 passed (12)Tout au vert. Il a poussé le changement et il est parti.
Lundi, 10:30.
Lucía lui a montré une capture d'écran que la boutique avait envoyée. C'était l'écran de paiement, celui qu'on voit avant de payer. Tout en haut, à côté d'une commande qui n'existait pas encore, il y avait un bouton : « Imprimer le ticket ».
— Une cliente l'a imprimé et elle est partie, a dit Lucía. Elle a cru qu'elle avait déjà payé.
Iván n'avait pas touché à l'écran de paiement. Lucía a ouvert le terminal et a tapé une seule recherche :
$ grep -rn "from \"./Ticket\"" src
src/PaginaPedido.tsx:3:import { Ticket } from "./Ticket";
src/PaginaPago.tsx:5:import { Ticket } from "./Ticket";Deux écrans utilisaient le même Ticket. Quelqu'un, des mois plus tôt, avait voulu afficher un résumé de la commande sur l'écran de paiement et, au lieu d'en faire un, avait emprunté le ticket de l'autre. Ça a marché. Personne ne s'est plaint. Jusqu'au jour où le ticket a changé pour son écran, et où l'autre a changé avec lui.
— Le compilateur n'y est pour rien, a dit Lucía. Pour lui, qu'un écran utilise un composant d'un autre, c'est parfait. La question est ailleurs : à qui appartient Ticket.tsx ?
Dans l'API de l'épisode 6, Iván l'aurait su en une seconde. Ici, il n'y avait pas de paquets, seulement un tas.
— À l'écran de la commande, a-t-il répondu.
— Alors, si l'écran de la commande disparaît, que devient PaginaPago.tsx ?
— Il casse.
— Voilà. Ce fichier ne vit pas là où on le supprimerait.
Qu'est-ce qui change, et qu'est-ce qui ne change pas ?
Les règles du restaurant ne changent pas. Ce qui change, c'est la partie du restaurant : de la cuisine, on passe à la salle.
Dans les épisodes 5 et 6, nous avons monté la cuisine d'une boutique de commandes : une API qui reçoit le bon de commande, le cuisine et l'enregistre. Cet épisode, c'est la salle, ce que voit le client : l'écran où il passe sa commande et l'écran où il voit son ticket. Le modèle s'appelle estructura-react et il parle à l'API de l'épisode 6.
Les trois règles sur lesquelles nous avons refermé l'épisode 5 sont toujours là :
- Chacun à sa place. Le bouton ne sait pas ce qu'est une commande ; le formulaire ne sait pas que l'écran du ticket existe.
- Les flèches dans un seul sens. La page utilise la fonctionnalité ; la fonctionnalité n'utilise jamais la page.
- Ce qui entre, ce qui se garde et ce qui sort sont des choses différentes. Ce que répond l'API est vérifié à l'arrivée, avant d'être affiché.
Ce qui change, c'est la façon de découper le projet. En cuisine, nous avons découpé par couches, comme les étages d'un immeuble : tout ce qui sert à recevoir dans api, tout ce qui touche aux règles dans service. En salle, on découpe par fonctionnalité, comme les rayons d'un magasin : tout ce qui sert à « passer une commande » dans un dossier, tout ce qui sert à « voir ma commande » dans un autre.
Pourquoi une autre découpe ? Parce que, sur un écran, ce qu'on ajoute et ce qu'on supprime, c'est une fonctionnalité entière. La boutique ne te demandera jamais « supprime tous les hooks » ; elle te demandera « retire l'option de commander sur le web ».
| En salle | Dossier | Ce qu'il ne fait JAMAIS |
|---|---|---|
| Chaque service de la salle : prendre le bon de commande, remettre le ticket | features/<nombre>/ | Mettre la main dans le service d'à côté |
| La table, où les services se réunissent pour un client | pages/ | Cuisiner : ni appels à l'API ni règles |
| La vaisselle et les couverts : ils servent à tout et ne savent pas quel plat ils portent | shared/components/ui/ | Savoir ce qu'est une commande |
| Le passe-plat vers la cuisine | shared/api/ | Afficher quoi que ce soit |
| Le local : la porte, l'enseigne et le plan au cas où quelque chose tombe | app/ | Des règles métier |
| La répétition avant l'ouverture | test/ | Servir un vrai client |
La documentation historique de React dit que React n'impose pas de dossiers, « React doesn’t have opinions on how you put files into folders », et mentionne le fait de regrouper « by feature or route » [1]. Sers-t'en comme point de départ ; la règle concrète de ce modèle est une décision d'architecture, et c'est pour cela qu'il vaut mieux que quelque chose la surveille.
Où vit chaque fichier ?
Là où on le supprimerait. Si tu ne peux pas dire qui le supprimerait, tu ne sais pas encore où il va.
Voici l'arbre du modèle, avec ce qui compte pour la structure :
estructura-react/
├── package.json · package-lock.json
├── tsconfig.json solo «references»; los tres de abajo revisan
├── tsconfig.app.json · tsconfig.test.json · tsconfig.node.json
├── vite.config.ts servidor de desarrollo, proxy y pruebas
├── eslint.config.js las reglas del código y LAS FRONTERAS
├── docs/ARCHITECTURE.md quién importa a quién, en una hoja
├── herramientas/probar-frontera.sh
└── src/
├── app/ el local: rutas, encabezado, límite de error
├── pages/ una mesa por ruta: solo junta
├── features/
│ ├── carrito/ hacer un pedido
│ │ ├── components/ FormularioDeComanda.tsx
│ │ ├── hooks/ useCrearPedido.ts
│ │ ├── services/ crearPedido.ts
│ │ └── schemas/ comanda.ts
│ └── pedidos/ ver un pedido
│ ├── components/ ConsultaDelPedido.tsx · TicketDelPedido.tsx
│ ├── hooks/ usePedido.ts
│ ├── services/ buscarPedido.ts
│ └── schemas/ pedido.ts
├── shared/
│ ├── components/ui/ Boton · Campo · Aviso · Pagina
│ ├── api/ cliente.ts · problema.ts
│ ├── lib/ dinero.ts · fecha.ts
│ └── config/ entorno.ts
├── styles/ tokens.css · base.css
└── test/ el mismo árbol que src/Teste la règle avec trois fichiers :
TicketDelPedido.tsx. Si la boutique retire l'écran de la commande, il s'en va. Il vit dansfeatures/pedidos/.dinero.ts, qui convertit des centimes en pesos (47000en$470.00). Le ticket et le formulaire l'utilisent. Si l'un des deux s'en va, l'autre en a toujours besoin : il n'appartient à aucun des deux. Il vit dansshared/lib/.Boton.tsx. Tout le monde l'utilise et il ne sait rien du métier. Il vit dansshared/components/ui/.
Avec cette règle, le Ticket.tsx d'Iván avait un seul propriétaire, l'écran de la commande. L'écran de paiement ne pouvait pas l'emprunter. S'il avait besoin d'un résumé, il avait deux chemins, et les deux sont dans le modèle : faire le sien, ou laisser une page réunir les deux pièces.
Qu'est-ce qui va dans chaque dossier ?
Six dossiers, chacun avec son rôle et son « jamais ».
features/, les services de la salle
Une fonctionnalité, c'est quelque chose que la boutique sait nommer : carrito (passer une commande) et pedidos (voir une commande). À l'intérieur, quatre sous-dossiers, et seulement ceux qu'il faut :
components/: ce qui s'affiche.hooks/: l'état de l'écran.usePedidosait si la commande est en cours de chargement, prête, si elle n'existe pas ou s'il y a eu une erreur, et rien de plus.services/: l'appel à l'API.buscarPedidodemandeGET /v1/pedidos/{id}.schemas/: la forme des données, écrite avec zod. Le schéma fait deux travaux : il vérifie ce qui arrive, et c'est de lui que sort le type TypeScript.
export const esquemaDePedido = z.object({
id: z.uuid(),
estado: z.string(),
total_centavos: z.number().int().nonnegative(),
creado_en: z.iso.datetime({ offset: true }),
lineas: z.array(esquemaDeLinea).min(1),
});
export type Pedido = z.infer<typeof esquemaDePedido>;Pourquoi vérifier ce que répond ta propre API ? Parce que les types de TypeScript n'arrivent pas jusqu'au navigateur : si l'API change un champ, l'écran affiche undefined sans que personne ne prévienne. Le schéma, c'est le bon de commande vérifié à la porte.
Cette graine enseigne la frontière et les quatre états avec deux appels. Dans un projet de produit, les types du contrat se génèrent depuis OpenAPI et l'état distant se gère avec un cache d'état distant (TanStack Query, SWR ou un autre). Ici, nous utilisons des schemas et un hook uniquement parce que l'API d'exercice ne publie pas encore ce contrat ; c'est une limite déclarée, pas la destination finale.
Le « jamais » : une fonctionnalité n'importe rien d'une autre. Ni un composant, ni un hook, ni un type.
pages/, la table
Une page par route, et elle ne fait que réunir. Voici la page de la commande, en entier :
export function PedidoPage() {
const { id = "" } = useParams();
return (
<Pagina titulo="Tu pedido">
<ConsultaDelPedido key={id} id={id} />
</Pagina>
);
}La page de nouvelle commande fait quelque chose de plus fin. Le formulaire du carrito ne navigue pas : il prévient « j'ai créé la commande » avec une fonction que la page lui passe, alCrear, et c'est la page qui décide d'aller au ticket. Ainsi, le carrito ne sait pas que l'écran du ticket existe.
Le « jamais » : une page n'appelle pas l'API, ne garde pas de règles et n'écrit pas de HTML en vrac. Elle compose.
Pour cette application, nous utilisons features/ et shared/ : la page compose directement des pièces de sa fonctionnalité et de ui. Dans un frontend plus grand, une couche intermédiaire de sections peut être utile ; ici, ce serait un dossier de trop.
shared/components/ui/, la vaisselle
Boton, Campo, Aviso et Pagina. Ce sont des pièces qui servent sur n'importe quel écran parce qu'elles ne savent rien du métier. Campo relie son libellé et son erreur pour qu'un lecteur d'écran les annonce ; il ne sait pas que c'est une adresse e-mail.
Il n'y a pas de index.ts qui réexporte le dossier : chaque import dit de quel fichier il vient. Vite demande d'éviter ces fichiers, parce qu'ils obligent à télécharger toutes les pièces pour en utiliser une, « loading more files than required on the initial page load » [8].
Le « jamais » : une pièce de ui n'appelle pas l'API et ne connaît aucune fonctionnalité.
shared/api/, le passe-plat
cliente.ts est le seul endroit du projet qui appelle fetch. C'est pourquoi il peut faire trois choses dont personne d'autre n'a à se souvenir :
- Un délai maximal pour chaque appel : 8 secondes, avec
AbortSignal.timeout. Si l'API ne répond pas, l'écran le dit au lieu de rester en chargement. - Un identifiant dans chaque appel,
X-Request-ID, que le backend de l'épisode 6 écrit dans son journal. - Une phrase fixe pour chaque erreur. L'API répond avec Problem Details, et son champ
error_codedit laquelle c'était (SIN_EXISTENCIAS). Le client cherche ce code dans une table et affiche sa phrase : « No hay piezas suficientes de uno de los productos. » (Il n'y a pas assez de pièces pour l'un des produits.) Le texte du backend n'arrive jamais à l'écran : il peut contenir des détails que la personne n'a pas à voir.
Le « jamais » : le passe-plat n'affiche rien et ne sait pas quelle fonctionnalité l'utilise.
app/, le local
C'est ici que se montent les routes, l'en-tête et le plan au cas où quelque chose tombe. Deux décisions comptent. La première : chaque écran voyage dans son propre morceau de code et ne se télécharge que lorsque quelqu'un le visite. C'est le chargement différé (lazy).
La seconde : chaque écran a sa limite d'erreur. Une limite d'erreur (Error Boundary) est un composant qui attrape la panne de ce qu'il contient et affiche autre chose à la place. La documentation de React le dit pour le chargement différé : si la promesse qui télécharge le code échoue, « React will throw the rejection reason for the nearest Error Boundary to handle » [2]. Dans le modèle, si un écran ne peut pas être téléchargé ou plante à l'affichage, l'en-tête reste, et apparaissent « No pudimos mostrar esta pantalla. » (Nous n'avons pas pu afficher cet écran.), un bouton « Reintentar » (Réessayer) et un lien vers l'accueil.
test/, la répétition
Les tests vivent dans src/test/, avec le même arbre que src/ : celui du client est dans src/test/shared/api/cliente.test.ts. Ils utilisent Vitest pour s'exécuter et Testing Library pour utiliser l'écran comme le fait une personne : ils cherchent le bouton par son nom, « Hacer el pedido » (Passer la commande), pas par une classe CSS. Son principe l'explique : « The more your tests resemble the way your software is used, the more confidence they can give you » [3].
Les tests parlent à une fausse API, montée avec MSW, qui intercepte fetch sans changer une ligne du code. Si un test demande quelque chose qui n'a pas été déclaré, il échoue : aucun ne sort sur le réseau.
Un détail qui ne se voit pas dans l'arbre : trois tsconfig, un par programme (l'application, vite.config.ts dans Node et les tests), et tsc -b vérifie les trois en mode strict, qui est activé d'office depuis TypeScript 6 [9]. Le tsconfig.json de la racine ne fait que les énumérer : là, tsc --noEmit ne vérifie pas un seul fichier et sort au vert.
Qui surveille les frontières ?
ESLint, avec un plugin qui sait quel dossier est lequel. Et un script qui démontre qu'il surveille vraiment.
Pour TypeScript, import { TicketDelPedido } from "../../pedidos/components/TicketDelPedido" à l'intérieur du carrito est un import comme un autre. Pour Vite aussi. Le compilateur vérifie que les types concordent, pas qui est propriétaire de quoi.
Celui qui le vérifie, c'est eslint-plugin-boundaries. Dans eslint.config.js, chaque dossier de src/ est un « élément » avec un type (funcionalidad, pagina, ui, api), et en dessous vient qui peut importer qui. Ce qui n'est pas permis est interdit :
{
from: { element: { type: "funcionalidad" } },
disallow: { to: { element: { type: "funcionalidad" } } },
message:
"la funcionalidad {{ from.element.captured.nombre }} importa las tripas de {{ to.element.captured.nombre }}: lo que comparten va en shared/, o lo junta una página",
},Une règle qu'on n'a jamais vue au rouge, on ne sait pas si elle existe. C'est pourquoi le modèle apporte herramientas/probar-frontera.sh. Sur une copie temporaire, il fait un contrôle, qui doit passer proprement, et trois violations semées : le carrito qui importe le ticket, un bouton de ui qui importe le client de l'API et un fichier en vrac dans src/. Chaque violation semée doit compiler et se construire, et le lint doit échouer avec une seule erreur de la règle attendue dans le fichier semé, lue dans le rapport JSON d'ESLint.
1/4 control: el proyecto tal como está
✅ compiló, construyó y el lint revisó 38 archivos sin un error
2/4 violación: el carrito importa el ticket de la funcionalidad de pedidos
✅ compiló y construyó, y el lint falló con un solo error, en src/features/carrito/components/VistaPrevia.tsx:
la funcionalidad carrito importa las tripas de pedidos: lo que comparten va en shared/, o lo junta una página
3/4 violación: un átomo de ui importa el cliente de la API
✅ compiló y construyó, y el lint falló con un solo error, en src/shared/components/ui/Boton.tsx:
ui no puede importar de api: mira la tabla de quién importa a quién en docs/ARCHITECTURE.md
4/4 archivo suelto: un archivo en src/, fuera de toda carpeta con papel
✅ compiló y construyó, y el lint falló con un solo error, en src/Utilidades.ts:
File does not match any file pattern and does not belong to any known element
✅ frontera: se sostiene (las tres siembras compilaron, construyeron y el lint las detuvo, cada una por su razón)Et si le script mentait ? Nous l'avons saboté de cinq façons (la règle désactivée, les fonctionnalités autorisées à s'importer entre elles, sans la règle des fichiers en vrac, un croisement déjà écrit et sans dépendances installées). Les cinq fois, il est sorti avec le code 1. C'est le même rôle que celui qu'a joué ArchUnit dans l'épisode 6, avec un autre outil.
Qu'avons-nous mesuré ?
Tout ce que ce texte affirme du modèle vient de son exécution, le 19 novembre 2026, sous macOS avec Node 26.13.1. Sous Linux, c'est la CI de GitHub qui l'a exécuté, sur Ubuntu 26.04 avec Node 26.13.0 et 26.13.1 : 37 sur 37, le même budget de 100,14 kB et la frontière qui tient. Sous Linux Mint, il n'a pas été testé.
Les tests. npm run verificar lance cinq étapes et s'arrête à la première qui échoue : types, lint, format, tests et build. Les tests se terminent ainsi :
Test Files 11 passed (11)
Tests 37 passed (37)Ce sont 37 tests dans 11 fichiers, comptés deux fois : dans la console et dans le rapport JSON de Vitest, qui donne 37 37 0 (total, réussis, échoués). On les compte dans le rapport et non dans le code de sortie : un fichier qui n'arrive pas à importer quelque chose sort comme (0 test), et le total baisse sans que rien ne passe au rouge.
Le build. Ce que télécharge le navigateur :
| Morceau | Taille | Compressé |
|---|---|---|
| Celui d'entrée, que toute visite télécharge | 318 kB | 100,5 kB |
| Le client de l'API avec zod, partagé | 85,5 kB | 24,9 kB |
| L'écran de nouvelle commande | 3,1 kB | 1,5 kB |
| L'écran du ticket | 2,6 kB | 1,2 kB |
| Les styles | 2,1 kB | 0,8 kB |
Dans ce build, les deux pages sortent en chunks séparés : NuevoPedidoPage pèse 3,12 kB et PedidoPage 2,62 kB. Une nouvelle route doit conserver ce chargement différé ; mesure de nouveau, car les chunks partagés peuvent changer.
Ces chiffres sont un instantané, pas un budget de taille. Une application qui va en production a besoin d'un plafond versionné qui fasse échouer le build, de deux builds identiques et d'un pipeline avec lint, types, tests, build, Sonar, audit et recherche de secrets. Cette graine se contente encore de mesurer ; quand elle grandit, ajoute ces verrous avant de traiter la taille comme une règle. Le modèle apporte déjà le plafond (110 kB pour le morceau d'entrée), l'audit et les deux builds ; Sonar et la recherche de secrets manquent, et le README le dit.
Le contrat, en direct. Nous avons démarré l'API de l'épisode 6 (estructura-quarkus, commit 33e89f5) avec jwebserver -b 127.0.0.1 -p 9090 -d "$PWD/ejemplo/inventario" et java -jar target/quarkus-app/quarkus-run.jar, sur le port 8080. npm run contrato a donné 4 sur 4 ; sans l'API, 4 au rouge. Ensuite, npm run dev. En développement, le navigateur demande tout à Vite, et Vite transmet à l'API ce qui commence par /v1 (le server.proxy de vite.config.ts [10]) ; pour le navigateur, c'est une seule origine et il n'y a pas besoin de configurer CORS. Par ce chemin : la commande a été créée (201), son ticket a été lu et a passé le schéma, et les trois erreurs sont arrivées avec leur code et leur phrase fixe : SIN_EXISTENCIAS (409), PRODUCTO_NO_EXISTE (422) et PEDIDO_NO_ENCONTRADO (404). Le détail qu'a écrit le backend (« De TAZA-01 se pidieron 4 y hay 3 » : on a demandé 4 TAZA-01 et il y en a 3) est resté dans son journal, à côté du même X-Request-ID qu'a envoyé l'écran. Avec l'API éteinte, Vite répond 502 et l'écran dit « Algo salió mal de nuestro lado. Intenta de nuevo. » (Quelque chose s'est mal passé de notre côté. Réessaie.), sans un seul détail technique.
Les versions, mesurées ce jour-là avec npm view : React 19.3.1, React Router 8.5.2, Vite 8.3.8, TypeScript 7.0.2, Vitest 5.1.1, zod 4.6.7 et ESLint 10.15.0. TypeScript 7 « does not ship with an API » pour l'instant [4] : il n'expose pas l'API que typescript-eslint utilise pour analyser TypeScript ; c'est pourquoi le modèle installe TS 7 pour tsc et conserve TS 6 sous le nom typescript pour cet outil, comme le recommande son annonce.
Quelles sont cinq erreurs fréquentes ?
Toutes ont été mesurées sur le modèle. Les cinq passent certains contrôles et échouent à un autre.
1. La fonctionnalité qui emprunte les pièces d'une autre
C'est l'erreur d'Iván. Ça compile, ça se construit et ça passe les tests, parce que chaque test vérifie son écran et qu'aucun ne vérifie qui importe qui. Le jour où quelqu'un change la pièce pour son écran, l'autre change aussi. Comment l'éviter : la règle d'ESLint. Si les deux écrans ont besoin de la même chose, la page réunit les deux pièces, ou bien ce qui est commun monte dans shared/ avec un nom qui dit ce qu'il fait. Si deux copies changent pour la même raison, on les réunit tout de suite ; si elles ne font que se ressembler, on les tolère tant que chacune change de son côté, et à la troisième la décision s'écrit, sans obligation de la faire monter.
2. L'alias que le lint ne voit pas
Beaucoup de projets écrivent @/features/pedidos/... au lieu de ../../pedidos/.... Tu le déclares dans tsconfig et dans Vite, ça compile et ça se construit. Mais si ESLint ne sait pas le résoudre, le plugin ne sait pas vers quel fichier il pointe. Sa documentation le dit : par défaut, « non-relative imports that cannot be resolved are categorized as external » [5]. Et ce qui est externe, comme React, n'est pas vérifié. Mesuré : avec l'alias, le carrito a importé le ticket de pedidos et le lint est passé ; le même import avec un chemin relatif, dans le même projet, a été arrêté. Comment l'éviter : le modèle utilise des chemins relatifs. Si tu veux l'alias, ajoute aussi eslint-import-resolver-typescript : avec lui, le même import est arrêté (mesuré). Et ajoute au script de la frontière une violation semée avec alias, pour qu'il te prévienne si un jour il cesse de le voir.
3. Le test que personne ne lance
Tu écris Boton.test.tsx à côté de Boton.tsx, comme dans beaucoup de tutoriels. Dans ce modèle, Vitest ne cherche que dans src/test/ (par défaut, il chercherait dans tout le projet, avec **/*.{test,spec}.?(c|m)[jt]s?(x) [6]). Mesuré : un test qui échoue toujours, écrit à côté du bouton, a laissé le total à 37 passed et le code de sortie à 0. Comment l'éviter : les tests vont dans src/test/, et la CI du modèle apporte une étape qui passe au rouge si elle trouve un fichier de test en dehors de ce dossier (nous l'avons testé à la main, en en semant un).
4. L'écran blanc sous l'en-tête
Tu mets la limite d'erreur sur la même route que celle qui télécharge le code de l'écran. Ça semble logique. Mesuré avec React Router 8.5.2 : si le code ne peut pas être téléchargé (une connexion qui se coupe, une nouvelle version publiée pendant que la personne naviguait), l'erreur est bien enregistrée, mais l'écran de secours n'apparaît pas. Il reste l'en-tête et, en dessous, rien. Comment l'éviter : la limite va un niveau au-dessus, sur une route sans chemin propre qui enveloppe celle qui télécharge le code. Dans le modèle, c'est conLimiteDeError qui le fait, et le test de rutas.test.tsx y veille : si tu remets la limite sur la même route, il passe au rouge (mesuré : 36 sur 37).
5. Se fier à vite build pour les types
Vite construit rapidement parce qu'il ne vérifie pas les types. Sa documentation le dit : « Vite only performs transpilation on .ts files and does NOT perform type checking » [7]. Mesuré : avec export const total: number = "cien", vite build est sorti au vert et tsc -b au rouge, avec TS2322. Comment l'éviter : npm run typecheck avant de construire, et dans la CI.
| # | Erreur | Ce qui la laisse passer | Ce qui l'arrête |
|---|---|---|---|
| 1 | Une fonctionnalité importe des pièces d'une autre | tsc, vite build, les tests | La règle d'ESLint |
| 2 | Alias @/ non résolu dans ESLint | tsc, vite build et le lint | Le resolver de TypeScript et une violation semée avec alias |
| 3 | Test à côté du composant | Vitest, qui ne le lance pas | Tests dans src/test/ et l'étape de la CI |
| 4 | Limite d'erreur sur la route du lazy | tsc, le lint, un test qui ne simule pas la panne | La limite un niveau au-dessus et son test |
| 5 | Erreur de types | vite build | tsc -b |
Exercice : peux-tu mettre le formulaire sur l'écran du ticket ?
Tu vas faire ce qu'a fait quelqu'un dans le projet d'Iván, voir que tout passe sauf le lint, puis le faire bien.
La boutique demande quelque chose de raisonnable : que, sur l'écran du ticket, on puisse passer une autre commande sur place, sans revenir à l'accueil. Il te faut Node 26.13 ou plus récent (node --version), Git 2.23 ou plus récent (pour git restore) et bash ; environ 25 minutes. Sous Windows, utilise WSL. L'exercice complet a été testé sous macOS.
Étape 1. Clone et vérifie que tout est au vert.
git clone https://github.com/HabilMX/estructura-react
cd estructura-react
npm ci
npm run verificar
bash herramientas/probar-frontera.shTu dois voir Tests 37 passed (37), puis le build et, à la fin du script, ✅ frontera: se sostiene. N'utilise ce clone que pour t'exercer : ainsi, tout changement que tu y verras vient de l'exercice. Sous macOS, npm ci peut signaler que fsevents apporte des scripts d'installation non approuvés : c'est un avertissement, pas une erreur, et l'étape 1 sort au vert sans eux.
Étape 2. Écris d'abord le test. Celui-ci dit ce que la boutique a demandé : sur l'écran du ticket, en plus du ticket, il y a un bouton « Hacer el pedido ».
cat > src/test/pages/OtroPedido.test.tsx <<'EOF'
import { render, screen } from "@testing-library/react";
import { createMemoryRouter, RouterProvider } from "react-router";
import { expect, it } from "vitest";
import { PedidoPage } from "../../pages/PedidoPage";
import { ID_DE_EJEMPLO } from "../comun/servidor";
it("en la pantalla del ticket se puede hacer otro pedido", async () => {
const rutas = createMemoryRouter([{ path: "/pedidos/:id", Component: PedidoPage }], {
initialEntries: [`/pedidos/${ID_DE_EJEMPLO}`],
});
render(<RouterProvider router={rutas} />);
expect(await screen.findByRole("table")).toBeInTheDocument();
expect(screen.getByRole("button", { name: "Hacer el pedido" })).toBeInTheDocument();
});
EOF
npm testIl passe au rouge, et pour la bonne raison : Unable to find an accessible element with the role "button" and name "Hacer el pedido". Le résumé dit Tests 1 failed | 37 passed (38).
Étape 3. Prédis, puis cède à la tentation. Le ticket, c'est ConsultaDelPedido qui l'affiche, dans features/pedidos/. Le plus rapide est d'y mettre le formulaire du carrito. Avant de le faire, note : est-ce que ça compile ? Les tests passent-ils ? Et le lint ?
Ouvre src/features/pedidos/components/ConsultaDelPedido.tsx. Ajoute cette ligne à côté des autres import :
import { FormularioDeComanda } from "../../carrito/components/FormularioDeComanda";Et remplace le cas "listo" par celui-ci :
case "listo":
return (
<>
<TicketDelPedido pedido={estado.pedido} />
<FormularioDeComanda alCrear={() => {}} />
</>
);Maintenant lance, une par une :
npm test
npm run typecheck
npm run build
npm run lintLes tests disent Tests 38 passed (38) : le tien passe déjà. Les types et le build, sans une erreur. Le lint, non :
src/features/pedidos/components/ConsultaDelPedido.tsx
3:37 error la funcionalidad pedidos importa las tripas de carrito: lo que comparten va en shared/, o lo junta una página boundaries/dependenciesRegarde le alCrear={() => {}} : la consultation de la commande n'a nulle part où envoyer le client quand elle a fini, parce que naviguer n'est pas son travail. Le code te disait déjà que le formulaire ne vivait pas là.
Étape 4. Interroge le script.
bash herramientas/probar-frontera.shIl passe au rouge sans dépasser le contrôle : ❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla del lint. C'est le contrôle qui travaille : il ne peut pas démontrer que le lint sait échouer si ton projet le fait déjà échouer.
Étape 5. Remets seulement ce que tu as touché, et fais-le à la table. D'abord, regarde ce qui a changé :
git diff --stat -- src/features/pedidos/components/ConsultaDelPedido.tsxTu dois voir 1 file changed, 7 insertions(+), 1 deletion(-). Si tu vois autre chose, c'est à toi : sauvegarde-le avant de continuer. S'il n'y a que l'exercice, remets ce fichier. git restore ne touche que les chemins que tu lui donnes :
git restore src/features/pedidos/components/ConsultaDelPedido.tsxCette fois, oui : c'est la page qui réunit deux fonctionnalités. Écris PedidoPage ainsi :
cat > src/pages/PedidoPage.tsx <<'EOF'
import { useNavigate, useParams } from "react-router";
import { FormularioDeComanda } from "../features/carrito/components/FormularioDeComanda";
import { ConsultaDelPedido } from "../features/pedidos/components/ConsultaDelPedido";
import { Pagina } from "../shared/components/ui/Pagina";
/** El ticket de un pedido y, debajo, la forma de hacer otro. La página junta las dos. */
export function PedidoPage() {
const { id = "" } = useParams();
const navegar = useNavigate();
return (
<Pagina titulo="Tu pedido">
<ConsultaDelPedido key={id} id={id} />
<FormularioDeComanda alCrear={(nuevo) => navegar(`/pedidos/${nuevo}`)} />
</Pagina>
);
}
EOF
npm run verificar
bash herramientas/probar-frontera.sh
git status --shortTout au vert : Tests 38 passed (38) et ✅ frontera: se sostiene. Maintenant, alCrear a bien quelque chose à faire : la page sait où aller. Et git status montre ton travail, rien de plus :
M src/pages/PedidoPage.tsx
?? src/test/pages/OtroPedido.test.tsxComment savoir que tu l'as bien fait : tu as vu trois issues. Le test rouge à l'étape 2. Tout vert sauf le lint à l'étape 3, et le script rouge à l'étape 4. Et tout vert à l'étape 5, avec le même test que tu as demandé au début. Si, à l'étape 3, les types signalent une erreur, vérifie que le import est bien resté en haut, à côté des autres.
À retenir
Trois questions à poser à ton projet React cette semaine.
- Choisis un fichier de
src/au hasard. Qui le supprimerait ? Si la réponse est « personne » ou « ça dépend », il n'a pas encore de propriétaire. - Quel composant est importé depuis deux fonctionnalités différentes ?
grep -rn "from \"../../" src/featuresest un bon début. Chaque résultat qui traverse vers une autre fonctionnalité est un bouton qui peut bouger sur deux écrans. - Qu'est-ce qui passe au rouge si quelqu'un écrit ce croisement demain ? Si la réponse est « rien », la structure de ton projet est une habitude, pas une règle.
Ce que laissent les sept épisodes
Sept langages, sept modèles, et la même question : à qui appartient ce fichier, et qu'est-ce qui passe au rouge si je le mets ailleurs ?
Nous avons commencé avec Go et un standard de dossiers qui n'en était pas un. Nous avons continué avec Python, le paquet qui passait sur ta machine et cassait une fois installé ; avec Rust et la fonction que personne ne pouvait tester ; avec TypeScript et l'import qui compilait et ne démarrait pas. Ensuite, nous avons monté la même cuisine deux fois, avec Spring Boot et avec Quarkus, et aujourd'hui la salle, avec React.
Les outils ont changé chaque dimanche. Ce qui s'est répété, c'est ceci :
- Chaque dossier a un rôle et un « jamais ». Si tu ne peux pas dire ce qui ne va jamais dans un dossier, le dossier n'a pas de rôle.
- Une règle qu'on n'a jamais vue au rouge, on ne sait pas si elle existe. C'est pourquoi chaque modèle apporte sa frontière qui sait échouer : un compilateur, un ArchUnit ou un lint qui passe au rouge avec une erreur semée, et un contrôle qui démontre qu'il n'est pas passé au rouge pour une autre raison.
- On compte dans le rapport, pas dans le code de sortie. En TypeScript, une exécution sans fichiers de test sortait avec
0; en Quarkus, une classe de tests qui ne démarrait pas laissait ses tests comme ignorés ; aujourd'hui, un fichier qui n'arrive pas à importer sort comme(0 test). Les trois fois, le code de sortie disait que tout allait bien. - Un nouveau dossier doit résoudre un problème que tu as déjà. Aucun modèle n'apporte ce qui ne fait pas encore mal, et chaque README dit quand l'ajouter.
Iván ne cherche plus le bouton dans un tas de quatre-vingts fichiers. Il cherche la fonctionnalité, et à l'intérieur il trouve le bouton.
Le modèle et le cours
- Modèle : github.com/HabilMX/estructura-react. Il s'utilise comme modèle GitHub ou se clone. Le README explique chaque dossier, la frontière avec sa sortie réelle, les erreurs mesurées, ce qu'il n'apporte pas et les verrous qui lui manquent pour la production, quand ajouter chaque chose et comment retirer l'exemple.
docs/ARCHITECTURE.mdapporte le tableau de qui importe qui, sur une feuille. Le code est sous MIT ; le texte et les explications, sous CC BY-SA 4.0. - Pour le voir travailler avec la cuisine : démarre l'API de estructura-quarkus (mesurée avec son commit
33e89f5) comme le dit son README, sur le port 8080 ; lancenpm run contratopuisnpm run devdans ce modèle. Ouvrehttp://localhost:5173/, commande deuxTAZA-01et regarde ton ticket. - Versions : Node 26.13 ou plus récent ; les autres, dans le README. Testé sous macOS arm64 et, dans la CI de GitHub, sur Ubuntu 26.04 ; sous Linux Mint, pas encore.
- Cours de React de Hábil : si les hooks, les routes ou les tests avec Testing Library sont nouveaux pour toi, commence par là : Cours de React. Et si tu n'as pas lu les épisodes 5 et 6, mieux vaut les lire : celui-ci tient pour acquis les rôles du restaurant.
J'écris à partir de ce que nous voyons tous les jours chez Hábil, où nous construisons des systèmes pour la banque, l'assurance et les entreprises au Mexique. Si, au travail ou à l'école, ton équipe tombe sur un dépôt que personne ne sait par où prendre, parlons-en : habil.mx
Que fait Hábil ?
Nous enseignons la programmation avec ce que nous utilisons pour construire : du code testé, expliqué et ouvert.
Cette série naît du même endroit que nos cours. Le Cours de React mène d'un tableau de bord d'un seul bloc à une appli de plusieurs écrans qui tient la route, et nous le publions en accès ouvert, sous licence Creative Commons ; sa leçon 0 monte le projet avec Vite, ses trois tsconfig et la structure par fonctionnalité, la même base qu'utilise le modèle de cet article. Et le catalogue compte d'autres cours de programmation, gratuits, avec du code testé et expliqué pas à pas.
Découvre le Cours de React et le catalogue des Cours de programmation.
Nous construisons aussi des applications web, mobiles et de bureau sur mesure, avec des frontends organisés par fonctionnalité, que l'on peut maintenir et faire grandir sans casser ce qui est à côté, pour la banque, l'assurance et les entreprises. Si ton frontend est déjà un tas de fichiers que personne n'ose déplacer, on peut le remettre en ordre sans arrêter l'exploitation : découvre Applications web, mobiles et de bureau. Demande ton premier échange, sans frais. Nous y examinons s'il vaut mieux configurer ce que ton équipe a déjà, utiliser un produit ou construire, et ce qu'elle recevrait dans chaque cas. Écris-nous sur WhatsApp.
Sources consultées le 19 novembre 2026. Les citations en anglais sont reproduites telles quelles.
Références
- React, « File Structure » (questions fréquentes de la documentation historique de React) : « Is there a recommended way to structure React projects? ». https://legacy.reactjs.org/docs/faq-structure.html
- React, « lazy ». https://react.dev/reference/react/lazy
- Testing Library, « Guiding Principles ». https://testing-library.com/docs/guiding-principles
- D. Rosenwasser, « Announcing TypeScript 7.0 » : « Running Side-by-Side with TypeScript 6.0 », blog de TypeScript, 8 juillet 2026. https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
- JS Boundaries, « Settings » :
boundaries/flag-as-external. https://www.jsboundaries.dev/docs/setup/settings/ - Vitest, « include ». https://vitest.dev/config/include
- Vite, « Features » : « Transpile Only ». https://vite.dev/guide/features
- Vite, « Performance » : « Avoid Barrel Files ». https://vite.dev/guide/performance
- TypeScript, « TypeScript 6.0 » : « strict is now true by default ». https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
- Vite, « Server Options » :
server.proxy. https://vite.dev/config/server-options
Votre activité fait face à ces défis ?
Vous préférez l'e-mail ? Écrivez-nous à hola@habil.mx