Skip to content
Frontend21 min

The structure of a project (7): the button that moved on two screens

By · co-founder and Chief Executive Officer of Hábil ·

A React screen with TypeScript and Vite, sliced by feature: where each file lives, what ESLint stops and what we measured on the template.

The structure of a project · installment 7 of 7 · React

Scenario: the characters and the story are made up. The technical data and the quotes carry their source at the end.

In 1 minute

  • The restaurant in installments 5 and 6 had a kitchen. This is the dining room: what the customer sees. The rules are the same (everyone does their own job, arrows in one direction only); what changes is how the project is sliced.
  • On the server it's sliced by layers: waiter, cook, pantry. On the screen it's sliced by feature: "placing an order" and "viewing my order" each live in their own folder, with everything that belongs to them inside.
  • The rule that decides it: a file lives where it would be deleted. If tomorrow the store stops selling on the web, you delete one folder and its page, and nothing else breaks.
  • One feature doesn't import another's pieces. TypeScript and Vite don't see it: it compiles, builds and passes the tests. In the template, ESLint stops it, and a script proves that it does.
  • Measured on the template: 37 tests green, read from the report; each screen travels in its own chunk of code, of 3 kB, and the contract with the API from installment 6 was tested live.
  • For Monday: search your project for a component that is imported from two different feature folders. That's the button that is going to move on two screens.

In this article

  1. What happened on Friday at 17:40?
  2. What changes and what doesn't?
  3. Where does each file live?
  4. What goes in each folder?
  5. Who watches the boundaries?
  6. What did we measure?
  7. What are five frequent mistakes?
  8. Exercise: can you put the form on the receipt screen?
  9. Key takeaways
  10. What the seven installments leave behind
  11. The template and the course
  12. What does Hábil do?
  13. References

What happened on Friday at 17:40?

Iván moved a button on the receipt screen. On Monday, the button had also moved on the payment screen.

Friday, 17:40. Third floor.

The job was small. The store wanted the "Print receipt" button at the top, next to the order number, and not all the way at the bottom, where nobody saw it. Iván opened the src/ folder of the React project and found eighty files at the same level: Ticket.tsx, Boton.tsx, api.ts, utils.ts, PaginaPago.tsx, useDatos.ts. No folder said whose each thing was.

He looked for the button and found it in Ticket.tsx. He moved it up three lines. He ran the usual:

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

Everything green. He pushed the change and left.

Monday, 10:30.

Lucía showed him a screenshot the store had sent. It was the payment screen, the one you see before paying. At the very top, next to an order that didn't exist yet, there was a button: "Print receipt".

"A customer printed it and left," Lucía said. "She thought she had already paid."

Iván hadn't touched the payment screen. Lucía opened the terminal and typed a single search:

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

Two screens used the same Ticket. Someone, months earlier, had wanted to show an order summary on the payment screen and, instead of making one, borrowed the other screen's receipt. It worked. Nobody complained. Until the receipt changed for its own screen, and the other one changed with it.

"The compiler isn't to blame," Lucía said. "As far as it's concerned, one screen using another's component is perfectly fine. The question is a different one: who owns Ticket.tsx?"

In the API from installment 6, Iván would have known in a second. Here there were no packages, only a pile.

"The order screen," he answered.

"Then, if the order screen disappears, what happens to PaginaPago.tsx?"

"It breaks."

"There it is. That file doesn't live where it would be deleted."

What changes and what doesn't?

The restaurant's rules don't change. The part of the restaurant does: from the kitchen we move to the dining room.

In installments 5 and 6 we set up the kitchen of an order store: an API that receives the order slip, cooks it and stores it. This installment is the dining room, what the customer sees: the screen where they place their order and the screen where they see their receipt. The template is called estructura-react and it talks to the API from installment 6.

The three rules we closed installment 5 with are still here:

  1. Everyone does their own job. The button doesn't know what an order is; the form doesn't know the receipt screen exists.
  2. Arrows in one direction only. The page uses the feature; the feature never uses the page.
  3. What comes in, what gets stored and what goes out are different things. What the API answers is checked on arrival, before rendering it.

What changes is how the project is sliced. In the kitchen we sliced by layers, like the floors of a building: everything about receiving in api, everything about the rules in service. In the dining room it's sliced by feature, like the departments of a store: everything about "placing an order" in one folder, everything about "viewing my order" in another.

Why a different slice? Because on a screen, what gets added and deleted is a whole feature. The store is never going to ask you to "delete all the hooks"; it's going to ask you to "remove the option to order on the web".

What changes and what doesn't?
In the dining roomFolderWhat it NEVER does
Each dining-room service: taking the order slip, handing over the receiptfeatures/<nombre>/Reach into the service next to it
The table, where the services come together for one customerpages/Cook: no API calls and no rules
The dishes and cutlery: they work for everything and don't know what dish they carryshared/components/ui/Know what an order is
The pass-through window to the kitchenshared/api/Render anything
The restaurant itself (the premises): the door, the sign and the plan in case something goes downapp/Business rules
The rehearsal before openingtest/Serve a real customer

React's legacy documentation says React doesn't impose folders, «React doesn’t have opinions on how you put files into folders», and mentions grouping «by feature or route» [1]. Use it as a starting point; this template's concrete rule is an architecture decision, and that's why it's worth having something watch over it.

Where does each file live?

Where it would be deleted. If you can't answer who would delete it, you don't know yet where it goes.

This is the template's tree, with what matters for the 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/

Try the rule with three files:

  • TicketDelPedido.tsx. If the store removes the order screen, it goes. It lives in features/pedidos/.
  • dinero.ts, which converts cents into pesos (47000 into $470.00). The receipt and the form use it. If one of the two goes, the other still needs it: it belongs to neither. It lives in shared/lib/.
  • Boton.tsx. Everybody uses it and it knows nothing about the business. It lives in shared/components/ui/.

With that rule, Iván's Ticket.tsx had a single owner, the order screen. The payment screen couldn't borrow it. If it needed a summary, it had two paths, and both are in the template: make its own, or have a page put the two pieces together.

What goes in each folder?

Six folders, each with its role and its "never".

features/, the dining-room services

A feature is something the store knows how to name: carrito (placing an order) and pedidos (viewing an order). Inside, four subfolders, and only the ones that are needed:

  • components/: what gets rendered.
  • hooks/: the screen's state. usePedido knows whether the order is loading, ready, doesn't exist or there was an error, and nothing else.
  • services/: the call to the API. buscarPedido requests GET /v1/pedidos/{id}.
  • schemas/: the shape of the data, written with zod. The schema does two jobs: it checks what arrives, and the TypeScript type comes out of it.
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>;

Why check what your own API answers? Because TypeScript's types don't reach the browser: if the API changes a field, the screen renders undefined without anyone warning you. The schema is the order slip checked at the door.

This seed teaches the boundary and the four states with two calls. In a product project, the contract's types are generated from OpenAPI and remote state is handled with a remote-state cache (TanStack Query, SWR or another). Here we use schemas and a hook only because the practice API doesn't publish that contract yet; it's a declared limitation, not the final destination.

The "never": a feature imports nothing from another one. Not a component, not a hook, not a type.

pages/, the table

One page per route, and it only puts things together. This is the complete order page:

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

The new-order page does something finer. The cart's form doesn't navigate: it announces "I created the order" with a function the page passes to it, alCrear, and the page decides to go to the receipt. That way the cart doesn't know the receipt screen exists.

The "never": a page doesn't call the API, doesn't hold rules and doesn't write loose HTML. It composes.

For this app we use features/ and shared/: the page composes pieces of its feature and of ui directly. In a larger frontend an intermediate layer of sections may be worth it; here it would be one folder too many.

shared/components/ui/, the dishes

Boton, Campo, Aviso and Pagina. They are pieces that work on any screen because they know nothing about the business. Campo ties its label and its error together so that a screen reader announces them; it doesn't know it's an email.

There is no index.ts that re-exports the folder: each import says which file it comes from. Vite asks you to avoid those files, because they force you to download all the pieces in order to use one, «loading more files than required on the initial page load» [8].

The "never": a ui piece doesn't call the API or know about a feature.

shared/api/, the pass-through window

cliente.ts is the only place in the project that calls fetch. That's why it can do three things nobody else has to remember:

  • A timeout for each call: 8 seconds, with AbortSignal.timeout. If the API doesn't answer, the screen says so instead of staying stuck loading.
  • An identifier on each call, X-Request-ID, which the server from installment 6 writes in its log.
  • A fixed message for each error. The API answers with Problem Details, and its error_code field says which one it was (SIN_EXISTENCIAS). The client looks that code up in a table and shows its message: «No hay piezas suficientes de uno de los productos.» (There aren't enough pieces of one of the products.) The server's text never reaches the screen: it may carry details the person has no reason to see.

The "never": the window doesn't render anything or know which feature uses it.

app/, the restaurant itself

This is where the routes, the header and the plan in case something goes down are mounted. Two decisions matter. The first: each screen travels in its own chunk of code and is downloaded only when someone visits it. That's lazy loading (lazy).

The second: each screen has its error boundary. An error boundary (Error Boundary) is a component that catches the failure of what it has inside and renders something else in its place. React's documentation says it for lazy loading: if the promise that downloads the code fails, «React will throw the rejection reason for the nearest Error Boundary to handle» [2]. In the template, if a screen can't be downloaded or crashes while rendering, the header stays, and what appears is «No pudimos mostrar esta pantalla.» (We couldn't show this screen.), a «Reintentar» (Retry) button and a link to the home page.

test/, the rehearsal

The tests live in src/test/, with the same tree as src/: the client's test is in src/test/shared/api/cliente.test.ts. They use Vitest to run and Testing Library to use the screen the way a person uses it: they look for the button by its name («Hacer el pedido», Place the order), not by a CSS class. Its principle explains it: «The more your tests resemble the way your software is used, the more confidence they can give you» [3].

The tests talk to a fake API, built with MSW, which intercepts fetch without changing a line of the code. If a test requests something that wasn't declared, it fails: none of them goes out to the network.

A detail you can't see in the tree: three tsconfig files, one per program (the application, vite.config.ts in Node and the tests), and tsc -b checks all three in strict mode, which has been on by default since TypeScript 6 [9]. The root tsconfig.json only lists them: there, tsc --noEmit doesn't check a single file and comes out green.

Who watches the boundaries?

ESLint, with a plugin that knows which folder is which. And a script that proves it really is watching.

For TypeScript, import { TicketDelPedido } from "../../pedidos/components/TicketDelPedido" inside the cart is an import like any other. For Vite, too. The compiler checks that the types match, not who owns what.

The one that checks it is eslint-plugin-boundaries. In eslint.config.js each folder in src/ is an "element" with a type (funcionalidad, pagina, ui, api), and below that goes who can import whom. What isn't allowed is forbidden:

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

A rule that has never been seen red: you can't tell whether it exists. That's why the template ships herramientas/probar-frontera.sh. In a temporary copy it runs a control, which has to pass clean, and three planted violations: the cart importing the receipt, a ui button importing the API client, and a loose file in src/. Each planted violation has to compile and build, and the lint has to fail with a single error from the expected rule in the planted file, read from ESLint's JSON report.

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)

And what if the script lied? We sabotaged it in five ways (the rule turned off, the features allowed to import each other, without the loose-file rule, a crossing already written, and without the dependencies installed). All five times it exited with code 1. It's the same role ArchUnit played in installment 6, with a different tool.

What did we measure?

Everything this text claims about the template came from running it, on November 19, 2026, on macOS with Node 26.13.1. On Linux, GitHub's CI ran it, on Ubuntu 26.04 with Node 26.13.0 and 26.13.1: 37 of 37, the same budget of 100.14 kB and the boundary that holds. It hasn't been tested on Linux Mint.

The tests. npm run verificar runs five steps and stops at the first one that fails: types, lint, formatting, tests and build. The tests end like this:

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

That's 37 tests in 11 files, counted twice: in the console and in Vitest's JSON report, which gives 37 37 0 (total, passed, failed). They are counted in the report and not in the exit code: a file that fails to import something shows up as (0 test), and the total goes down without anything turning red.

The build. What the browser downloads:

The build. What the browser downloads
ChunkSizeCompressed
The entry chunk, which every visit downloads318 kB100.5 kB
The API client with zod, shared85.5 kB24.9 kB
The new-order screen3.1 kB1.5 kB
The receipt screen2.6 kB1.2 kB
The styles2.1 kB0.8 kB

In this build, the two pages come out as separate chunks: NuevoPedidoPage weighs 3.12 kB and PedidoPage 2.62 kB. A new route must keep that lazy loading; measure again, because the shared chunks can change.

These figures are a snapshot, not a budget. An application that goes to production needs a versioned cap that makes the build fail, two identical builds and a pipeline with lint, types, tests, build, Sonar, an audit and a secrets scan. This seed still only measures; as it grows, add those locks before treating size as a rule. The template already ships the cap (110 kB for the entry chunk), the audit and the two builds; Sonar and the secrets scan are missing, and the README says so.

The contract, live. We started the API from installment 6 (estructura-quarkus, commit 33e89f5) with jwebserver -b 127.0.0.1 -p 9090 -d "$PWD/ejemplo/inventario" and java -jar target/quarkus-app/quarkus-run.jar, on 8080. npm run contrato gave 4 of 4; without the API, 4 red. Then, npm run dev. In development, the browser asks Vite for everything and Vite passes on to the API whatever starts with /v1 (the server.proxy in vite.config.ts [10]); for the browser it's a single origin and there's no need to configure CORS. Along that path: the order was created (201), its receipt was read and passed the schema, and the three errors arrived with their code and their fixed message: SIN_EXISTENCIAS (409), PRODUCTO_NO_EXISTE (422) and PEDIDO_NO_ENCONTRADO (404). The detail the server wrote («De TAZA-01 se pidieron 4 y hay 3», 4 of TAZA-01 were ordered and there are 3) stayed in its log, next to the same X-Request-ID the screen sent. With the API turned off, Vite answers 502 and the screen says «Algo salió mal de nuestro lado. Intenta de nuevo.» (Something went wrong on our side. Try again.), without a single technical detail.

The versions, measured that day with 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 and ESLint 10.15.0. TypeScript 7 «does not ship with an API» yet [4]: it doesn't expose the API that typescript-eslint uses to analyze TypeScript; that's why the template installs TS 7 for tsc and keeps TS 6 under the name typescript for that tool, as its announcement recommends.

What are five frequent mistakes?

All of them were measured on the template. All five pass some check and fail another.

1. The feature that borrows another one's pieces

It's Iván's mistake. It compiles, builds and passes the tests, because each test checks its own screen and none checks who imports whom. The day someone changes the piece for their screen, the other one changes too. How to avoid it: the ESLint rule. If the two screens need the same thing, the page puts the two pieces together, or the common part moves up to shared/ with a name that says what it does. If two copies change for the same reason, they are merged right away; if they only look alike, they are tolerated as long as each one changes on its own, and at the third one the decision gets written down, with no obligation to move it up.

2. The alias the lint doesn't see

Many projects write @/features/pedidos/... instead of ../../pedidos/.... You declare it in tsconfig and in Vite, and it compiles and builds. But if ESLint doesn't know how to resolve it, the plugin doesn't know which file it points to. Its documentation says so: by default, «non-relative imports that cannot be resolved are categorized as external» [5]. And what's external, like React, isn't checked. Measured: with the alias, the cart imported the orders feature's receipt and the lint passed; the same import with a relative path, in the same project, was stopped. How to avoid it: the template uses relative paths. If you want the alias, also add eslint-import-resolver-typescript: with it, the same import is stopped (measured). And add a planted violation with an alias to the boundary script, so that it warns you if one day it stops seeing it.

3. The test nobody runs

You write Boton.test.tsx next to Boton.tsx, as in many tutorials. In this template, Vitest only looks in src/test/ (by default it would look in the whole project, with **/*.{test,spec}.?(c|m)[jt]s?(x) [6]). Measured: a test that always fails, written next to the button, left the total at 37 passed and the exit code at 0. How to avoid it: the tests go in src/test/, and the template's CI ships a step that turns red if it finds a test file outside of there (we tested it by hand, planting one).

4. The blank screen under the header

You put the error boundary on the same route that downloads the screen's code. It seems the logical thing. Measured with React Router 8.5.2: if the code can't be downloaded (a connection that drops, a new version published while the person was browsing), the error gets logged, but the fallback screen doesn't appear. The header stays and, below it, nothing. How to avoid it: the error boundary goes one level up, on a pathless route that wraps the one that downloads the code. In the template, conLimiteDeError does it, and the test in rutas.test.tsx guards it: if you move the error boundary back to the same route, it turns red (measured: 36 of 37).

5. Trusting vite build for the types

Vite builds fast because it doesn't check types. Its documentation says so: «Vite only performs transpilation on .ts files and does NOT perform type checking» [7]. Measured: with export const total: number = "cien", vite build came out green and tsc -b red, with TS2322. How to avoid it: npm run typecheck before building, and in the CI.

5. Trusting vite build for the types
#MistakeWhat lets it throughWhat stops it
1One feature imports another's piecestsc, vite build, the testsThe ESLint rule
2Alias @/ not resolved in ESLinttsc, vite build and the lintThe TypeScript resolver and a planted violation with an alias
3Test next to the componentVitest, which doesn't run itTests in src/test/ and the CI step
4Error boundary on the lazy routetsc, the lint, a test that doesn't simulate the failureThe error boundary one level up and its test
5Type errorvite buildtsc -b

Exercise: can you put the form on the receipt screen?

You're going to do what someone did in Iván's project, see that everything passes except the lint, and then do it right.

The store asks for something reasonable: that on the receipt screen you can place another order right there, without going back to the home page. You need Node 26.13 or newer (node --version), Git 2.23 or newer (for git restore) and bash; about 25 minutes. On Windows, use WSL. The full exercise was tested on macOS.

Step 1. Clone it and check that everything is green.

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

You should see Tests 37 passed (37), then the build and, at the end of the script, ✅ frontera: se sostiene. Use this clone only for practice: that way, every change you see in it belongs to the exercise. On macOS, npm ci may warn that fsevents brings install scripts that haven't been approved: it's a warning, not an error, and step 1 comes out green without them.

Step 2. Write the test first. This one says what the store asked for: on the receipt screen, besides the receipt, there is a «Hacer el pedido» button.

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

It turns red, and for the right reason: Unable to find an accessible element with the role "button" and name "Hacer el pedido". The summary says Tests 1 failed | 37 passed (38).

Step 3. Predict, and then give in to temptation. The receipt is rendered by ConsultaDelPedido, in features/pedidos/. The fastest thing is to drop the cart's form in there. Before you do it, write it down: does it compile? Do the tests pass? And the lint?

Open src/features/pedidos/components/ConsultaDelPedido.tsx. Add this line next to the other import lines:

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

And replace the "listo" case with this one:

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

Now run, one by one:

npm test
npm run typecheck
npm run build
npm run lint

The tests say Tests 38 passed (38): yours now passes. The types and the build, without an error. The 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

Look at the alCrear={() => {}}: the order lookup has nowhere to send the customer when it finishes, because navigating isn't its job. The code was already telling you the form didn't live there.

Step 4. Ask the script.

bash herramientas/probar-frontera.sh

It turns red without getting past the control: ❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla del lint. That's the control at work: it can't prove that the lint knows how to fail if your project already has it failing.

Step 5. Revert only what you touched, and do it at the table. First, look at what changed:

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

You should see 1 file changed, 7 insertions(+), 1 deletion(-). If you see anything else, it's yours: save it before going on. If only the exercise's change is there, revert that file. git restore only touches the paths you give it:

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

Now then: the one that puts two features together is the page. Write PedidoPage like this:

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

Everything green: Tests 38 passed (38) and ✅ frontera: se sostiene. Now alCrear does have something to do: the page knows where to go. And git status shows your work, nothing else:

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

How you know you did it right: you saw three outcomes. The red test in step 2. Everything green except the lint in step 3, and the script red in step 4. And everything green in step 5, with the same test you asked for at the beginning. If in step 3 the types report an error, check that the import ended up at the top, next to the others.

Key takeaways

Three questions to ask your React project this week.

  1. Pick a file in src/ at random. Who would delete it? If the answer is "nobody" or "it depends", it doesn't have an owner yet.
  2. Which component is imported from two different features? grep -rn "from \"../../" src/features is a good start. Each result that crosses into another feature is a button that can move on two screens.
  3. What turns red if someone writes that crossing tomorrow? If the answer is "nothing", your project's structure is a habit, not a rule.

What the seven installments leave behind

Seven languages, seven templates, and the same question: who owns this file, and what turns red if I put it somewhere else?

We started with Go and a folder standard that wasn't a standard. We went on with Python, the package that passed on your machine and failed when installed; with Rust and the function nobody could test; with TypeScript and the import that compiled and didn't start. Then we set up the same kitchen twice, with Spring Boot and with Quarkus, and today the dining room, with React.

The tools changed every Sunday. What repeated was this:

  • Each folder has a role and a "never". If you can't say what never goes in a folder, the folder doesn't have a role.
  • If a rule has never been seen red, you can't tell whether it exists. That's why each template ships its boundary that knows how to fail: a compiler, an ArchUnit or a lint that turns red with a planted error, and a control that proves it didn't turn red for some other reason.
  • You count in the report, not in the exit code. In TypeScript, a run with no test files exited with 0; in Quarkus, a test class that didn't start left its tests as skipped; today, a file that fails to import shows up as (0 test). All three times, the exit code said everything was fine.
  • A new folder has to solve a problem you already have. No template ships what doesn't hurt yet, and each README says when to add it.

Iván no longer looks for the button in a pile of eighty files. He looks for the feature, and inside it he finds the button.

The template and the course

  • Template: github.com/HabilMX/estructura-react. Use it as a GitHub template or clone it. The README explains each folder, the boundary with its real output, the measured mistakes, what it doesn't include and the locks it still lacks for production, when to add each thing and how to remove the example. docs/ARCHITECTURE.md has the table of who imports whom on one sheet. The code is MIT; the text and explanations are CC BY-SA 4.0.
  • To see it working with the kitchen: start the API from estructura-quarkus (measured with its commit 33e89f5) as its README says, on port 8080; run npm run contrato and then npm run dev in this template. Open http://localhost:5173/, order two TAZA-01 and look at your receipt.
  • Versions: Node 26.13 or newer; the rest, in the README. It was tested on macOS arm64 and, in GitHub's CI, on Ubuntu 26.04; on Linux Mint, not yet.
  • Hábil's React course: if hooks, routes or testing with Testing Library are new to you, start there: React course. And if you didn't read installments 5 and 6, it's worth reading them: this one takes the restaurant's roles as known.

I write from what we see every day at Hábil, where we build systems for banking, insurance and companies in Mexico. If at work or at school you run into a repository nobody knows where to touch, let's talk: habil.mx

What does Hábil do?

We teach programming with the same things we use to build: tested, explained and open code.

This series comes from the same place as our courses. The React course takes a single-piece dashboard to a multi-screen app that holds up, and we publish it openly, under a Creative Commons license; its lesson 0 sets up the project with Vite, its three tsconfig files and the feature-based structure, the same foundation this article's template uses. And the catalog has more programming courses, free and with code tested and explained step by step.

See the React course and the Programming courses catalog.

We also build custom web, mobile and desktop apps, with frontends organized by feature that can be maintained and grown without breaking what sits next to them, for banking, insurance and companies. If your frontend is already a pile of files nobody dares to move, that can be put in order without stopping operations: see Web, mobile and desktop apps. Request your first conversation, at no cost. In it we review whether it makes sense to configure what you already have, use a product or build, and what you would get in each case. Write to us on WhatsApp.

Sources accessed on November 19, 2026. Quotes in English are reproduced as is.

References

  1. React, «File Structure» (frequently asked questions in React's legacy documentation): «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», TypeScript blog, July 8, 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