Saltar al contenido
Frontend21 min

La estructura de un proyecto (7): el botón que se movió en dos pantallas

Por · cofundador y Chief Executive Officer de Hábil ·

Una pantalla de React con TypeScript y Vite, cortada por funcionalidad: dónde vive cada archivo, qué detiene ESLint y lo que medimos en la plantilla.

La estructura de un proyecto · entrega 7 de 7 · React

Escenario: los personajes y la historia son inventados. Los datos técnicos y las citas llevan su fuente al final.

En 1 minuto

  • El restaurante de las entregas 5 y 6 tenía cocina. Ésta es la sala: lo que ve el cliente. Las reglas son las mismas (cada quien en lo suyo, las flechas en un solo sentido); lo que cambia es cómo se corta el proyecto.
  • En el servidor se corta por capas: mesero, cocinero, despensa. En la pantalla se corta por funcionalidad: «hacer un pedido» y «ver mi pedido» viven cada una en su carpeta, con todo lo suyo adentro.
  • La regla que lo decide: un archivo vive donde se borraría. Si mañana la tienda deja de vender por la web, borras una carpeta y su página, y nada más se rompe.
  • Una funcionalidad no importa las piezas de otra. TypeScript y Vite no lo ven: compila, construye y pasa las pruebas. En la plantilla lo detiene ESLint, y un guion demuestra que lo detiene.
  • Medido en la plantilla: 37 pruebas en verde, leídas del informe; cada pantalla viaja en su propio pedazo de código, de 3 kB, y el contrato con la API de la entrega 6 se probó en vivo.
  • Para el lunes: busca en tu proyecto un componente que se importa desde dos carpetas de funcionalidad distintas. Ése es el botón que se va a mover en dos pantallas.

En este artículo

  1. ¿Qué pasó el viernes a las 17:40?
  2. ¿Qué cambia y qué no?
  3. ¿Dónde vive cada archivo?
  4. ¿Qué va en cada carpeta?
  5. ¿Quién vigila las fronteras?
  6. ¿Qué medimos?
  7. ¿Cuáles son cinco errores frecuentes?
  8. Ejercicio: ¿puedes poner el formulario en la pantalla del ticket?
  9. Para llevar
  10. Lo que dejan las siete entregas
  11. La plantilla y el curso
  12. ¿Qué hace Hábil?
  13. Referencias

¿Qué pasó el viernes a las 17:40?

Iván movió un botón en la pantalla del ticket. El lunes, el botón también se había movido en la pantalla de pago.

Viernes, 17:40. Piso tres.

El encargo era chico. La tienda quería el botón «Imprimir ticket» arriba, junto al número del pedido, y no hasta abajo, donde nadie lo veía. Iván abrió la carpeta src/ del proyecto de React y encontró ochenta archivos al mismo nivel: Ticket.tsx, Boton.tsx, api.ts, utils.ts, PaginaPago.tsx, useDatos.ts. Ninguna carpeta decía de quién era cada cosa.

Buscó el botón y lo encontró en Ticket.tsx. Lo subió tres líneas. Corrió lo de siempre:

$ npx tsc -b
$ npm run build
✓ built in 412ms
$ npm test
      Tests  12 passed (12)

Todo en verde. Subió el cambio y se fue.

Lunes, 10:30.

Lucía le pasó una captura que había mandado la tienda. Era la pantalla de pago, la que se ve antes de pagar. Arriba de todo, junto a un pedido que todavía no existía, había un botón: «Imprimir ticket».

—Una clienta lo imprimió y se fue —dijo Lucía—. Creyó que ya había pagado.

Iván no había tocado la pantalla de pago. Lucía abrió la terminal y escribió una sola búsqueda:

$ grep -rn "from \"./Ticket\"" src
src/PaginaPedido.tsx:3:import { Ticket } from "./Ticket";
src/PaginaPago.tsx:5:import { Ticket } from "./Ticket";

Dos pantallas usaban el mismo Ticket. Alguien, meses antes, había querido mostrar un resumen del pedido en la pantalla de pago y, en vez de hacer uno, tomó prestado el ticket de la otra. Funcionó. Nadie se quejó. Hasta que el ticket cambió para su pantalla, y la otra cambió con él.

—El compilador no tiene la culpa —dijo Lucía—. Para él, que una pantalla use un componente de otra está perfecto. La pregunta es otra: ¿de quién es Ticket.tsx?

En la API de la entrega 6, Iván lo habría sabido en un segundo. Aquí no había paquetes, solo una pila.

—De la pantalla del pedido —contestó.

—Entonces, si la pantalla del pedido desaparece, ¿qué pasa con PaginaPago.tsx?

—Se rompe.

—Ahí está. Ese archivo no vive donde se borraría.

¿Qué cambia y qué no?

No cambian las reglas del restaurante. Cambia la parte del restaurante: de la cocina pasamos a la sala.

En las entregas 5 y 6 armamos la cocina de una tienda de pedidos: una API que recibe la comanda, la cocina y la guarda. Esta entrega es la sala, lo que ve el cliente: la pantalla donde hace su pedido y la pantalla donde ve su ticket. La plantilla se llama estructura-react y habla con la API de la entrega 6.

Las tres reglas con que cerramos la entrega 5 siguen aquí:

  1. Cada quien en lo suyo. El botón no sabe qué es un pedido; el formulario no sabe que existe la pantalla del ticket.
  2. Las flechas en un solo sentido. La página usa a la funcionalidad; la funcionalidad nunca usa a la página.
  3. Lo que entra, lo que se guarda y lo que sale son cosas distintas. Lo que contesta la API se revisa al llegar, antes de pintarlo.

Lo que cambia es cómo se corta el proyecto. En la cocina cortamos por capas, como los pisos de un edificio: todo lo de recibir en api, todo lo de las reglas en service. En la sala se corta por funcionalidad, como los departamentos de una tienda: todo lo de «hacer un pedido» en una carpeta, todo lo de «ver mi pedido» en otra.

¿Por qué otro corte? Porque en una pantalla lo que se agrega y se borra es una funcionalidad entera. La tienda nunca te va a pedir «borra todos los hooks»; te va a pedir «quita la opción de pedir por la web».

¿Qué cambia y qué no?
En la salaCarpetaLo que NUNCA hace
Cada servicio de la sala: tomar la comanda, entregar el ticketfeatures/<nombre>/Meter la mano en el servicio de al lado
La mesa, donde se juntan los servicios para un clientepages/Cocinar: ni llamadas a la API ni reglas
La loza y los cubiertos: sirven para todo y no saben qué platillo llevanshared/components/ui/Saber qué es un pedido
La ventanilla del pase a la cocinashared/api/Pintar algo
El local: la puerta, el letrero y el plan por si algo se caeapp/Reglas del negocio
El ensayo antes de abrirtest/Servir a un cliente de verdad

La documentación heredada de React dice que React no impone carpetas, «React doesn’t have opinions on how you put files into folders», y menciona agrupar «by feature or route» [1]. Úsalo como punto de partida; la regla concreta de esta plantilla es una decisión de arquitectura, y por eso conviene que algo la vigile.

¿Dónde vive cada archivo?

Donde se borraría. Si no puedes contestar quién lo borraría, todavía no sabes dónde va.

Éste es el árbol de la plantilla, con lo que importa para la estructura:

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/

Prueba la regla con tres archivos:

  • TicketDelPedido.tsx. Si la tienda quita la pantalla del pedido, se va. Vive en features/pedidos/.
  • dinero.ts, que convierte centavos en pesos (47000 en $470.00). Lo usan el ticket y el formulario. Si se va una de las dos, el otro lo sigue necesitando: no es de ninguna. Vive en shared/lib/.
  • Boton.tsx. Lo usa todo el mundo y no sabe nada del negocio. Vive en shared/components/ui/.

Con esa regla, el Ticket.tsx de Iván tenía un solo dueño, la pantalla del pedido. La pantalla de pago no podía tomarlo prestado. Si necesitaba un resumen, tenía dos caminos, y los dos están en la plantilla: hacer el suyo, o que una página junte las dos piezas.

¿Qué va en cada carpeta?

Seis carpetas, cada una con su papel y su «nunca».

features/, los servicios de la sala

Una funcionalidad es algo que la tienda sabe nombrar: carrito (hacer un pedido) y pedidos (ver un pedido). Adentro, cuatro subcarpetas, y solo las que hagan falta:

  • components/: lo que se pinta.
  • hooks/: el estado de la pantalla. usePedido sabe si el pedido está cargando, listo, si no existe o si hubo un error, y nada más.
  • services/: la llamada a la API. buscarPedido pide GET /v1/pedidos/{id}.
  • schemas/: la forma de los datos, escrita con zod. El esquema hace dos trabajos: revisa lo que llega y de él sale el tipo de 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>;

¿Por qué revisar lo que contesta tu propia API? Porque los tipos de TypeScript no llegan al navegador: si la API cambia un campo, la pantalla pinta undefined sin que nadie avise. El esquema es la comanda revisada en la puerta.

Esta semilla enseña la frontera y los cuatro estados con dos llamadas. En un proyecto de producto, los tipos del contrato se generan desde OpenAPI y el estado remoto se maneja con una caché de estado remoto (TanStack Query, SWR u otra). Aquí usamos schemas y un hook solo porque la API de práctica aún no publica ese contrato; es una limitación declarada, no el destino final.

El «nunca»: una funcionalidad no importa nada de otra. Ni un componente, ni un hook, ni un tipo.

pages/, la mesa

Una página por ruta, y solo junta. Ésta es la página del pedido completa:

export function PedidoPage() {
  const { id = "" } = useParams();
  return (
    <Pagina titulo="Tu pedido">
      <ConsultaDelPedido key={id} id={id} />
    </Pagina>
  );
}

La página de nuevo pedido hace algo más fino. El formulario del carrito no navega: avisa «creé el pedido» con una función que la página le pasa, alCrear, y la página decide ir al ticket. Así el carrito no sabe que la pantalla del ticket existe.

El «nunca»: una página no llama a la API, no guarda reglas y no escribe HTML suelto. Compone.

Para esta app usamos features/ y shared/: la página compone piezas de su funcionalidad y de ui directamente. En un frente más grande puede convenir una capa intermedia de secciones; aquí sería una carpeta de más.

shared/components/ui/, la loza

Boton, Campo, Aviso y Pagina. Son piezas que sirven en cualquier pantalla porque no saben nada del negocio. Campo une su etiqueta y su error para que un lector de pantalla los anuncie; no sabe que es un correo.

No hay un index.ts que reexporte la carpeta: cada import dice de qué archivo viene. Vite pide evitar esos archivos, porque obligan a bajar todas las piezas para usar una, «loading more files than required on the initial page load» [8].

El «nunca»: una pieza de ui no llama a la API ni conoce una funcionalidad.

shared/api/, la ventanilla del pase

cliente.ts es el único lugar del proyecto que llama a fetch. Por eso puede hacer tres cosas que nadie más tiene que recordar:

  • Un plazo para cada llamada: 8 segundos, con AbortSignal.timeout. Si la API no contesta, la pantalla lo dice en vez de quedarse cargando.
  • Un identificador en cada llamada, X-Request-ID, que el servidor de la entrega 6 escribe en su bitácora.
  • Una frase fija por cada error. La API contesta con Problem Details, y su campo error_code dice cuál fue (SIN_EXISTENCIAS). El cliente busca ese código en una tabla y muestra su frase: «No hay piezas suficientes de uno de los productos.» El texto del servidor nunca llega a la pantalla: puede traer detalles que la persona no tiene por qué ver.

El «nunca»: la ventanilla no pinta nada ni sabe qué funcionalidad la usa.

app/, el local

Aquí se montan las rutas, el encabezado y el plan por si algo se cae. Dos decisiones importan. La primera: cada pantalla viaja en su propio pedazo de código y se baja solo cuando alguien la visita. Es la carga diferida (lazy).

La segunda: cada pantalla tiene su límite de error. Un límite de error (Error Boundary) es un componente que atrapa la falla de lo que tiene adentro y pinta otra cosa en su lugar. La documentación de React lo dice para la carga diferida: si la promesa que baja el código falla, «React will throw the rejection reason for the nearest Error Boundary to handle» [2]. En la plantilla, si una pantalla no se puede bajar o truena al pintarse, el encabezado se queda, aparece «No pudimos mostrar esta pantalla.», un botón «Reintentar» y un enlace al inicio.

test/, el ensayo

Las pruebas viven en src/test/, con el mismo árbol que src/: la del cliente está en src/test/shared/api/cliente.test.ts. Usan Vitest para correr y Testing Library para usar la pantalla como la usa una persona: buscan el botón por su nombre («Hacer el pedido»), no por una clase de CSS. Su principio lo explica: «The more your tests resemble the way your software is used, the more confidence they can give you» [3].

Las pruebas le hablan a una API de mentira, armada con MSW, que intercepta fetch sin cambiar una línea del código. Si una prueba pide algo que no se declaró, falla: ninguna sale a la red.

Un detalle que no se ve en el árbol: tres tsconfig, uno por programa (la aplicación, vite.config.ts en Node y las pruebas), y tsc -b revisa los tres en modo estricto, que desde TypeScript 6 viene encendido [9]. El tsconfig.json de la raíz solo los enlista: ahí, tsc --noEmit no revisa un solo archivo y sale en verde.

¿Quién vigila las fronteras?

ESLint, con un plugin que sabe qué carpeta es cuál. Y un guion que demuestra que de verdad vigila.

Para TypeScript, import { TicketDelPedido } from "../../pedidos/components/TicketDelPedido" dentro del carrito es un import como cualquier otro. Para Vite, también. El compilador revisa que los tipos cuadren, no quién es dueño de qué.

Quien lo revisa es eslint-plugin-boundaries. En eslint.config.js cada carpeta de src/ es un «elemento» con un tipo (funcionalidad, pagina, ui, api) y debajo va quién puede importar a quién. Lo que no está permitido, está prohibido:

{
  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",
},

Una regla que nunca se ha visto en rojo no se sabe si existe. Por eso la plantilla trae herramientas/probar-frontera.sh. En una copia temporal hace un control, que tiene que pasar limpio, y tres siembras: el carrito que importa el ticket, un botón de ui que importa el cliente de la API y un archivo suelto en src/. Cada siembra tiene que compilar y construir, y el lint, fallar con un solo error de la regla esperada en el archivo sembrado, leído del informe JSON de 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)

¿Y si el guion mintiera? Lo saboteamos de cinco formas (la regla apagada, las funcionalidades autorizadas a importarse entre sí, sin la regla de archivos sueltos, un cruce ya escrito y sin dependencias instaladas). Las cinco veces salió con código 1. Es el mismo papel que hizo ArchUnit en la entrega 6, con otra herramienta.

¿Qué medimos?

Todo lo que este texto afirma de la plantilla salió de correrla, el 19 de noviembre de 2026, en macOS con Node 26.13.1. En Linux la corrió el CI de GitHub, en Ubuntu 26.04 con Node 26.13.0 y 26.13.1: 37 de 37, el mismo presupuesto de 100.14 kB y la frontera que se sostiene. En Linux Mint no se ha probado.

Las pruebas. npm run verificar corre cinco pasos y se para en el primero que falle: tipos, lint, formato, pruebas y construcción. Las pruebas terminan así:

 Test Files  11 passed (11)
      Tests  37 passed (37)

Son 37 pruebas en 11 archivos, contadas dos veces: en la consola y en el informe JSON de Vitest, que da 37 37 0 (total, pasaron, fallaron). Se cuentan en el informe y no en el código de salida: un archivo que no logra importar algo sale como (0 test), y el total baja sin que nada se ponga rojo.

La construcción. Lo que baja el navegador:

La construcción. Lo que baja el navegador
PedazoTamañoComprimido
El de entrada, que baja toda visita318 kB100.5 kB
El cliente de la API con zod, compartido85.5 kB24.9 kB
La pantalla de nuevo pedido3.1 kB1.5 kB
La pantalla del ticket2.6 kB1.2 kB
Los estilos2.1 kB0.8 kB

En este build, las dos páginas salen como chunks separados: NuevoPedidoPage pesa 3.12 kB y PedidoPage 2.62 kB. Una ruta nueva debe conservar esa carga diferida; vuelve a medir porque los chunks compartidos pueden cambiar.

Estas cifras son una fotografía, no un presupuesto. Una aplicación que va a producción necesita un tope versionado que haga fallar el build, dos builds idénticos y una canalización con lint, tipos, pruebas, build, Sonar, auditoría y barrido de secretos. Esta semilla todavía mide; al crecer, agrega esos candados antes de tratar el tamaño como una regla. La plantilla ya trae el tope (110 kB del pedazo de entrada), la auditoría y los dos builds; Sonar y el barrido de secretos faltan, y el README lo dice.

El contrato, en vivo. Levantamos la API de la entrega 6 (estructura-quarkus, commit 33e89f5) con jwebserver -b 127.0.0.1 -p 9090 -d "$PWD/ejemplo/inventario" y java -jar target/quarkus-app/quarkus-run.jar, en el 8080. npm run contrato dio 4 de 4; sin la API, 4 en rojo. Luego, npm run dev. En desarrollo, el navegador le pide todo a Vite y Vite le pasa a la API lo que empieza con /v1 (el server.proxy de vite.config.ts [10]); para el navegador es un solo origen y no hace falta configurar CORS. Por ese camino: el pedido se creó (201), su ticket se leyó y pasó el esquema, y los tres errores llegaron con su código y su frase fija: SIN_EXISTENCIAS (409), PRODUCTO_NO_EXISTE (422) y PEDIDO_NO_ENCONTRADO (404). El detalle que escribió el servidor («De TAZA-01 se pidieron 4 y hay 3») se quedó en su bitácora, junto al mismo X-Request-ID que mandó la pantalla. Con la API apagada, Vite contesta 502 y la pantalla dice «Algo salió mal de nuestro lado. Intenta de nuevo.», sin un solo detalle técnico.

Las versiones, medidas ese día con 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 y ESLint 10.15.0. TypeScript 7 «does not ship with an API» todavía [4]: no expone la API que typescript-eslint usa para analizar TypeScript; por eso la plantilla instala TS 7 para tsc y conserva TS 6 bajo el nombre typescript para esa herramienta, como recomienda su anuncio.

¿Cuáles son cinco errores frecuentes?

Todos se midieron en la plantilla. Los cinco pasan algún control y fallan otro.

1. La funcionalidad que toma prestadas las piezas de otra

Es el error de Iván. Compila, construye y pasa las pruebas, porque cada prueba revisa su pantalla y ninguna revisa quién importa a quién. El día que alguien cambia la pieza para su pantalla, la otra cambia también. Cómo se evita: la regla de ESLint. Si las dos pantallas necesitan lo mismo, la página junta las dos piezas, o lo común sube a shared/ con un nombre que diga qué hace. Si dos copias cambian por la misma razón, se juntan ya; si solo se parecen, se toleran mientras cada una cambie por su lado, y a la tercera la decisión se escribe, sin obligación de subirla.

2. El alias que el lint no ve

Muchos proyectos escriben @/features/pedidos/... en vez de ../../pedidos/.... Lo declaras en tsconfig y en Vite, compila y construye. Pero si ESLint no sabe resolverlo, el plugin no sabe a qué archivo apunta. Su documentación lo dice: por omisión, «non-relative imports that cannot be resolved are categorized as external» [5]. Y lo externo, como React, no se revisa. Medido: con el alias, el carrito importó el ticket de pedidos y el lint pasó; el mismo import con ruta relativa, en el mismo proyecto, se detuvo. Cómo se evita: la plantilla usa rutas relativas. Si quieres el alias, agrega también eslint-import-resolver-typescript: con él, el mismo import se detiene (medido). Y agrégale al guion de la frontera una siembra con alias, para que te avise si un día deja de verlo.

3. La prueba que nadie corre

Escribes Boton.test.tsx junto a Boton.tsx, como en muchos tutoriales. En esta plantilla, Vitest solo busca en src/test/ (por omisión buscaría en todo el proyecto, con **/*.{test,spec}.?(c|m)[jt]s?(x) [6]). Medido: una prueba que siempre falla, escrita junto al botón, dejó el total en 37 passed y el código de salida en 0. Cómo se evita: las pruebas van en src/test/, y el CI de la plantilla trae un paso que se pone rojo si encuentra un archivo de prueba fuera de ahí (lo probamos a mano, sembrando uno).

4. La pantalla en blanco debajo del encabezado

Pones el límite de error en la misma ruta que baja el código de la pantalla. Parece lo lógico. Medido con React Router 8.5.2: si el código no se puede bajar (una conexión que se corta, una versión nueva publicada mientras la persona navegaba), el error queda registrado, pero la pantalla de respaldo no aparece. Queda el encabezado y, debajo, nada. Cómo se evita: el límite va un nivel arriba, en una ruta sin dirección propia que envuelve a la que baja el código. En la plantilla lo hace conLimiteDeError, y la prueba de rutas.test.tsx lo cuida: si regresas el límite a la misma ruta, se pone roja (medido: 36 de 37).

5. Confiar en vite build para los tipos

Vite construye rápido porque no revisa tipos. Lo dice su documentación: «Vite only performs transpilation on .ts files and does NOT perform type checking» [7]. Medido: con export const total: number = "cien", vite build salió en verde y tsc -b en rojo, con TS2322. Cómo se evita: npm run typecheck antes de construir, y en el CI.

5. Confiar en vite build para los tipos
#ErrorQué lo deja pasarQué lo detiene
1Una funcionalidad importa piezas de otratsc, vite build, las pruebasLa regla de ESLint
2Alias @/ sin resolver en ESLinttsc, vite build y el lintEl resolver de TypeScript y una siembra con alias
3Prueba junto al componenteVitest, que no la correPruebas en src/test/ y el paso del CI
4Límite de error en la ruta del lazytsc, el lint, una prueba que no simule la fallaEl límite un nivel arriba y su prueba
5Error de tiposvite buildtsc -b

Ejercicio: ¿puedes poner el formulario en la pantalla del ticket?

Vas a hacer lo que hizo alguien en el proyecto de Iván, ver que todo pasa menos el lint, y luego hacerlo bien.

La tienda pide algo razonable: que en la pantalla del ticket se pueda hacer otro pedido ahí mismo, sin volver al inicio. Necesitas Node 26.13 o más nuevo (node --version), Git 2.23 o más nuevo (por git restore) y bash; unos 25 minutos. En Windows, usa WSL. El ejercicio completo se probó en macOS.

Paso 1. Clona y comprueba que todo está en verde.

git clone https://github.com/HabilMX/estructura-react
cd estructura-react
npm ci
npm run verificar
bash herramientas/probar-frontera.sh

Debes ver Tests 37 passed (37), luego la construcción y, al final del guion, ✅ frontera: se sostiene. Usa este clon solo para practicar: así, todo cambio que veas en él es del ejercicio. En macOS, npm ci puede avisar que fsevents trae scripts de instalación sin aprobar: es un aviso, no un error, y el paso 1 sale en verde sin ellos.

Paso 2. Escribe primero la prueba. Ésta dice lo que la tienda pidió: en la pantalla del ticket, además del ticket, hay un botón «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 test

Se pone roja, y por la razón correcta: Unable to find an accessible element with the role "button" and name "Hacer el pedido". El resumen dice Tests 1 failed | 37 passed (38).

Paso 3. Predice, y luego cae en la tentación. El ticket lo pinta ConsultaDelPedido, en features/pedidos/. Lo más rápido es meter ahí el formulario del carrito. Antes de hacerlo, anota: ¿compila? ¿Pasan las pruebas? ¿Y el lint?

Abre src/features/pedidos/components/ConsultaDelPedido.tsx. Agrega esta línea junto a los otros import:

import { FormularioDeComanda } from "../../carrito/components/FormularioDeComanda";

Y cambia el caso "listo" por éste:

    case "listo":
      return (
        <>
          <TicketDelPedido pedido={estado.pedido} />
          <FormularioDeComanda alCrear={() => {}} />
        </>
      );

Ahora corre, uno por uno:

npm test
npm run typecheck
npm run build
npm run lint

Las pruebas dicen Tests 38 passed (38): la tuya ya pasa. Los tipos y la construcción, sin un error. El lint, no:

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/dependencies

Fíjate en el alCrear={() => {}}: la consulta del pedido no tiene a dónde mandar al cliente cuando termina, porque navegar no es su trabajo. El código ya te estaba diciendo que el formulario no vivía ahí.

Paso 4. Pregúntale al guion.

bash herramientas/probar-frontera.sh

Se pone rojo sin pasar del control: ❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla del lint. Es el control trabajando: no puede demostrar que el lint sabe fallar si tu proyecto ya lo tiene fallando.

Paso 5. Regresa solo lo que tocaste, y hazlo en la mesa. Antes, mira qué cambió:

git diff --stat -- src/features/pedidos/components/ConsultaDelPedido.tsx

Debes ver 1 file changed, 7 insertions(+), 1 deletion(-). Si ves algo más, es tuyo: guárdalo antes de seguir. Si solo está lo del ejercicio, regresa ese archivo. git restore solo toca las rutas que le das:

git restore src/features/pedidos/components/ConsultaDelPedido.tsx

Ahora sí: quien junta dos funcionalidades es la página. Escribe PedidoPage así:

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 --short

Todo en verde: Tests 38 passed (38) y ✅ frontera: se sostiene. Ahora alCrear sí tiene algo que hacer: la página sabe a dónde ir. Y git status enseña tu trabajo, nada más:

 M src/pages/PedidoPage.tsx
?? src/test/pages/OtroPedido.test.tsx

Cómo sabes que lo hiciste bien: viste tres desenlaces. La prueba roja en el paso 2. Todo verde menos el lint en el paso 3, y el guion rojo en el paso 4. Y todo verde en el paso 5, con la misma prueba que pediste al principio. Si en el paso 3 los tipos marcan un error, revisa que el import haya quedado arriba, junto a los otros.

Para llevar

Tres preguntas para hacerle a tu proyecto de React esta semana.

  1. Elige un archivo de src/ al azar. ¿Quién lo borraría? Si la respuesta es «nadie» o «depende», todavía no tiene dueño.
  2. ¿Qué componente se importa desde dos funcionalidades distintas? grep -rn "from \"../../" src/features es un buen comienzo. Cada resultado que cruza a otra funcionalidad es un botón que se puede mover en dos pantallas.
  3. ¿Qué se pone rojo si alguien escribe ese cruce mañana? Si la respuesta es «nada», la estructura de tu proyecto es una costumbre, no una regla.

Lo que dejan las siete entregas

Siete lenguajes, siete plantillas, y la misma pregunta: ¿de quién es este archivo y qué se pone rojo si lo pongo en otro lado?

Empezamos con Go y un estándar de carpetas que no era estándar. Seguimos con Python, el paquete que pasaba en tu máquina y fallaba instalado; con Rust y la función que nadie podía probar; con TypeScript y el import que compilaba y no arrancaba. Luego armamos la misma cocina dos veces, con Spring Boot y con Quarkus, y hoy la sala, con React.

Las herramientas cambiaron cada domingo. Lo que se repitió fue esto:

  • Cada carpeta tiene un papel y un «nunca». Si no puedes decir qué nunca va en una carpeta, la carpeta no tiene papel.
  • Una regla que nunca se ha visto en rojo no se sabe si existe. Por eso cada plantilla trae su frontera que sabe fallar: un compilador, un ArchUnit o un lint que se pone rojo con un error sembrado, y un control que demuestra que no se puso rojo por otra razón.
  • Se cuenta en el informe, no en el código de salida. En TypeScript, una corrida sin archivos de prueba salía con 0; en Quarkus, una clase de pruebas que no arrancaba dejaba sus pruebas como saltadas; hoy, un archivo que no logra importar sale como (0 test). Las tres veces, el código de salida decía que todo estaba bien.
  • Una carpeta nueva tiene que resolver un problema que ya tienes. Ninguna plantilla trae lo que todavía no duele, y cada README dice cuándo agregarlo.

Iván ya no busca el botón en una pila de ochenta archivos. Busca la funcionalidad, y adentro encuentra el botón.

La plantilla y el curso

  • Plantilla: github.com/HabilMX/estructura-react. Se usa como plantilla de GitHub o se clona. El README explica cada carpeta, la frontera con su salida real, los errores medidos, lo que no trae y los candados que le faltan para producción, cuándo agregar cada cosa y cómo quitar el ejemplo. docs/ARCHITECTURE.md trae la tabla de quién importa a quién en una hoja. El código es MIT; el texto y las explicaciones son CC BY-SA 4.0.
  • Para verla trabajar con la cocina: levanta la API de estructura-quarkus (medida con su commit 33e89f5) como dice su README, en el puerto 8080; corre npm run contrato y luego npm run dev en esta plantilla. Abre http://localhost:5173/, pide dos TAZA-01 y mira tu ticket.
  • Versiones: Node 26.13 o más nuevo; las demás, en el README. Se probó en macOS arm64 y, en el CI de GitHub, en Ubuntu 26.04; en Linux Mint, todavía no.
  • Curso de React de Hábil: si los hooks, las rutas o las pruebas con Testing Library son nuevos para ti, empieza ahí: Curso de React. Y si no leíste las entregas 5 y 6, conviene leerlas: ésta da por sabidos los papeles del restaurante.

Escribo desde lo que vemos todos los días en Hábil, donde construimos sistemas para banca, seguros y empresas en México. Si en tu trabajo o en tu escuela se topan con un repositorio que nadie sabe dónde tocar, platiquemos: habil.mx

¿Qué hace Hábil?

Enseñamos a programar con lo mismo que usamos para construir: código probado, explicado y abierto.

Esta serie nace del mismo lugar que nuestros cursos. El Curso de React lleva un panel de una pieza a una aplicación de varias pantallas que se sostiene, y lo publicamos abierto, con licencia Creative Commons; su lección 0 arma el proyecto con Vite, sus tres tsconfig y la estructura por funcionalidad, la misma base que usa la plantilla de este artículo. Y en el catálogo hay más cursos de programación, gratuitos y con código probado y explicado paso a paso.

Mira el Curso de React y el catálogo de Cursos de programación.

También construimos apps web, móviles y de escritorio a la medida, con frentes ordenados por funcionalidad que se pueden mantener y crecer sin romper lo de al lado, para banca, seguros y empresas. Si tu frente ya es una pila de archivos que nadie se atreve a mover, eso se puede ordenar sin detener la operación: mira Apps web, móviles y de escritorio. Pide tu primera conversación, sin costo. En ella revisamos si conviene configurar lo que ya tienen, usar un producto o construir, y qué recibirían en cada caso. Escríbenos por WhatsApp.

Fuentes consultadas el 19 de noviembre de 2026. Las citas en inglés se reproducen tal cual.

Referencias

  1. React, «File Structure» (preguntas frecuentes de la documentación heredada de React): «Is there a recommended way to structure React projects?». https://legacy.reactjs.org/docs/faq-structure.html
  2. React, «lazy». https://react.dev/reference/react/lazy
  3. Testing Library, «Guiding Principles». https://testing-library.com/docs/guiding-principles
  4. D. Rosenwasser, «Announcing TypeScript 7.0»: «Running Side-by-Side with TypeScript 6.0», blog de TypeScript, 8 de julio de 2026. https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
  5. JS Boundaries, «Settings»: boundaries/flag-as-external. https://www.jsboundaries.dev/docs/setup/settings/
  6. Vitest, «include». https://vitest.dev/config/include
  7. Vite, «Features»: «Transpile Only». https://vite.dev/guide/features
  8. Vite, «Performance»: «Avoid Barrel Files». https://vite.dev/guide/performance
  9. TypeScript, «TypeScript 6.0»: «strict is now true by default». https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
  10. Vite, «Server Options»: server.proxy. https://vite.dev/config/server-options