Pular para o conteúdo
Frontend21 min

A estrutura de um projeto (7): o botão que se moveu em duas telas

Por · cofundador e Chief Executive Officer da Hábil ·

Uma tela em React com TypeScript e Vite, dividida por funcionalidade: onde mora cada arquivo, o que o ESLint barra e o que medimos no template.

A estrutura de um projeto · entrega 7 de 7 · React

Cenário: os personagens e a história são inventados. Os dados técnicos e as citações levam a fonte no final.

Em 1 minuto

  • O restaurante das entregas 5 e 6 tinha cozinha. Este é o salão: o que o cliente vê. As regras são as mesmas (cada um na própria função, as setas num só sentido); o que muda é como se fatia o projeto.
  • No servidor, fatia-se por camadas: garçom, cozinheiro, despensa. Na tela, fatia-se por funcionalidade: «fazer um pedido» e «ver meu pedido» moram cada uma na própria pasta, com tudo o que é dela dentro.
  • A regra que decide: um arquivo mora onde seria apagado. Se amanhã a loja deixar de vender pela web, apaga-se uma pasta e a página dela, e nada mais quebra.
  • Uma funcionalidade não importa as peças de outra. O TypeScript e o Vite não veem isso: compila, constrói e passa nos testes. No template, quem detém é o ESLint, e um script demonstra que ele detém.
  • Medido no template: 37 testes no verde, lidos do relatório; cada tela viaja no próprio pedaço de código, de 3 kB, e o contrato com a API da entrega 6 foi testado ao vivo.
  • Para segunda-feira: procure no projeto um componente que é importado a partir de duas pastas de funcionalidade diferentes. Esse é o botão que vai mudar em duas telas.

Neste artigo

  1. O que aconteceu na sexta às 17:40?
  2. O que muda e o que não muda?
  3. Onde mora cada arquivo?
  4. O que vai em cada pasta?
  5. Quem vigia as fronteiras?
  6. O que medimos?
  7. Quais são cinco erros frequentes?
  8. Exercício: dá para pôr o formulário na tela do tíquete?
  9. Para levar
  10. O que deixam as sete entregas
  11. O template e o curso
  12. O que a Hábil faz?
  13. Referências

O que aconteceu na sexta às 17:40?

O Iván mudou um botão de lugar na tela do tíquete. Na segunda-feira, o botão também tinha mudado na tela de pagamento.

Sexta-feira, 17:40. Terceiro andar.

A tarefa era pequena. A loja queria o botão «Imprimir tíquete» em cima, junto ao número do pedido, e não lá embaixo, onde ninguém o via. O Iván abriu a pasta src/ do projeto de React e encontrou oitenta arquivos no mesmo nível: Ticket.tsx, Boton.tsx, api.ts, utils.ts, PaginaPago.tsx, useDatos.ts. Nenhuma pasta dizia de quem era cada coisa.

Procurou o botão e o encontrou em Ticket.tsx. Subiu o botão três linhas. Rodou o de sempre:

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

Tudo no verde. Enviou a mudança e foi embora.

Segunda-feira, 10:30.

A Lucía lhe passou uma captura de tela que a loja tinha mandado. Era a tela de pagamento, a que aparece antes de pagar. Bem em cima, junto a um pedido que ainda não existia, havia um botão: «Imprimir tíquete».

— Uma cliente imprimiu e foi embora — disse a Lucía. — Achou que já tinha pagado.

O Iván não tinha mexido na tela de pagamento. A Lucía abriu o terminal e escreveu uma única busca:

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

Duas telas usavam o mesmo Ticket. Alguém, meses antes, tinha querido mostrar um resumo do pedido na tela de pagamento e, em vez de fazer um, pegou emprestado o tíquete da outra. Funcionou. Ninguém reclamou. Até que o tíquete mudou para a tela dele, e a outra mudou junto.

— O compilador não tem culpa — disse a Lucía. — Para ele, uma tela usar um componente de outra está perfeito. A pergunta é outra: de quem é Ticket.tsx?

Na API da entrega 6, o Iván teria sabido em um segundo. Aqui não havia pacotes, só uma pilha.

— Da tela do pedido — respondeu.

— Então, se a tela do pedido desaparecer, o que acontece com PaginaPago.tsx?

— Quebra.

— Aí está. Esse arquivo não mora onde seria apagado.

O que muda e o que não muda?

Não mudam as regras do restaurante. Muda a parte do restaurante: da cozinha passamos ao salão.

Nas entregas 5 e 6 montamos a cozinha de uma loja de pedidos: uma API que recebe a comanda, cozinha e guarda. Esta entrega é o salão, o que o cliente vê: a tela onde ele faz o pedido e a tela onde vê o tíquete. O template se chama estructura-react e fala com a API da entrega 6.

As três regras com que fechamos a entrega 5 continuam aqui:

  1. Cada um na própria função. O botão não sabe o que é um pedido; o formulário não sabe que a tela do tíquete existe.
  2. As setas num só sentido. A página usa a funcionalidade; a funcionalidade nunca usa a página.
  3. O que entra, o que se guarda e o que sai são coisas diferentes. O que a API responde é revisado ao chegar, antes de ser pintado.

O que muda é como se fatia o projeto. Na cozinha fatiamos por camadas, como os andares de um prédio: tudo o que é de receber em api, tudo o que é das regras em service. No salão, fatia-se por funcionalidade, como os departamentos de uma loja: tudo o que é de «fazer um pedido» numa pasta, tudo o que é de «ver meu pedido» em outra.

Por que outro corte? Porque numa tela o que se acrescenta e se apaga é uma funcionalidade inteira. A loja nunca vai pedir «apague todos os hooks»; vai pedir «tire a opção de pedir pela web».

O que muda e o que não muda?
No salãoPastaO que NUNCA faz
Cada serviço do salão: anotar a comanda, entregar o tíquetefeatures/<nombre>/Meter a mão no serviço ao lado
A mesa, onde os serviços se juntam para um clientepages/Cozinhar: nem chamadas à API nem regras
A louça e os talheres: servem para tudo e não sabem que prato levamshared/components/ui/Saber o que é um pedido
O passa-pratos para a cozinhashared/api/Pintar algo
O estabelecimento: a porta, o letreiro e o plano para o caso de algo cairapp/Regras do negócio
O ensaio antes de abrirtest/Servir um cliente de verdade

A documentação legada do React diz que o React não impõe pastas, «React doesn’t have opinions on how you put files into folders», e menciona agrupar «by feature or route» [1]. Use isso como ponto de partida; a regra concreta deste template é uma decisão de arquitetura, e por isso convém que algo a vigie.

Onde mora cada arquivo?

Onde seria apagado. Enquanto não há resposta para quem o apagaria, ainda não se sabe onde ele vai.

Esta é a árvore do template, com o que importa para a estrutura:

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 a regra com três arquivos:

  • TicketDelPedido.tsx. Se a loja tirar a tela do pedido, ele vai embora. Mora em features/pedidos/.
  • dinero.ts, que converte centavos em pesos (47000 em $470.00). É usado pelo tíquete e pelo formulário. Se um dos dois for embora, o outro continua precisando dele: não é de nenhum. Mora em shared/lib/.
  • Boton.tsx. Todo mundo usa e ele não sabe nada do negócio. Mora em shared/components/ui/.

Com essa regra, o Ticket.tsx do Iván tinha um único dono, a tela do pedido. A tela de pagamento não podia pegá-lo emprestado. Se precisava de um resumo, tinha dois caminhos, e os dois estão no template: fazer o próprio, ou uma página juntar as duas peças.

O que vai em cada pasta?

Seis pastas, cada uma com o próprio papel e o próprio «nunca».

features/, os serviços do salão

Uma funcionalidade é algo que a loja sabe nomear: carrito (fazer um pedido) e pedidos (ver um pedido). Dentro, quatro subpastas, e só as que fizerem falta:

  • components/: o que se pinta.
  • hooks/: o estado da tela. usePedido sabe se o pedido está carregando, pronto, se não existe ou se houve um erro, e nada mais.
  • services/: a chamada à API. buscarPedido pede GET /v1/pedidos/{id}.
  • schemas/: a forma dos dados, escrita com zod. O esquema faz dois trabalhos: revisa o que chega, e dele sai o tipo do 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 que revisar o que a própria API responde? Porque os tipos do TypeScript não chegam ao navegador: se a API mudar um campo, a tela pinta undefined sem que ninguém avise. O esquema é a comanda revisada na porta.

Esta semente ensina a fronteira e os quatro estados com duas chamadas. Num projeto de produto, os tipos do contrato são gerados a partir do OpenAPI, e o estado remoto é tratado com um cache de estado remoto (TanStack Query, SWR ou outro). Aqui usamos schemas e um hook só porque a API de prática ainda não publica esse contrato; é uma limitação declarada, não o destino final.

O «nunca»: uma funcionalidade não importa nada de outra. Nem um componente, nem um hook, nem um tipo.

pages/, a mesa

Uma página por rota, e ela só junta. Esta é a página do pedido completa:

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

A página de novo pedido faz algo mais fino. O formulário do carrito não navega: avisa «criei o pedido» com uma função que a página lhe passa, alCrear, e a página decide ir para o tíquete. Assim o carrito não sabe que a tela do tíquete existe.

O «nunca»: uma página não chama a API, não guarda regras e não escreve HTML solto. Compõe.

Para este app usamos features/ e shared/: a página compõe peças da funcionalidade dela e de ui diretamente. Num frontend maior pode convir uma camada intermediária de seções; aqui seria uma pasta a mais.

shared/components/ui/, a louça

Boton, Campo, Aviso e Pagina. São peças que servem em qualquer tela porque não sabem nada do negócio. Campo une o rótulo e o erro dele para que um leitor de tela os anuncie; não sabe que é um e-mail.

Não há um index.ts que reexporte a pasta: cada import diz de que arquivo vem. O Vite pede para evitar esses arquivos, porque obrigam a baixar todas as peças para usar uma, «loading more files than required on the initial page load» [8].

O «nunca»: uma peça de ui não chama a API nem conhece uma funcionalidade.

shared/api/, o passa-pratos

cliente.ts é o único lugar do projeto que chama fetch. Por isso pode fazer três coisas que ninguém mais precisa lembrar:

  • Um tempo limite para cada chamada: 8 segundos, com AbortSignal.timeout. Se a API não responder, a tela diz isso em vez de ficar carregando.
  • Um identificador em cada chamada, X-Request-ID, que o servidor da entrega 6 escreve no log.
  • Uma frase fixa para cada erro. A API responde com Problem Details, e o campo error_code diz qual foi (SIN_EXISTENCIAS). O cliente procura esse código numa tabela e mostra a frase correspondente: «No hay piezas suficientes de uno de los productos.» (Não há peças suficientes de um dos produtos.) O texto do servidor nunca chega à tela: pode trazer detalhes que a pessoa não tem por que ver.

O «nunca»: o passa-pratos não pinta nada nem sabe que funcionalidade o usa.

app/, o estabelecimento

Aqui se montam as rotas, o cabeçalho e o plano para o caso de algo cair. Duas decisões importam. A primeira: cada tela viaja no próprio pedaço de código e só é baixada quando alguém a visita. É o carregamento sob demanda (lazy).

A segunda: cada tela tem o próprio limite de erro. Um limite de erro (Error Boundary) é um componente que captura a falha do que tem dentro e pinta outra coisa no lugar. A documentação do React diz isso para o carregamento sob demanda: se a promessa que baixa o código falhar, «React will throw the rejection reason for the nearest Error Boundary to handle» [2]. No template, se uma tela não puder ser baixada ou quebrar ao ser pintada, o cabeçalho fica, aparecem «No pudimos mostrar esta pantalla.» (Não foi possível mostrar esta tela.), um botão «Reintentar» (Tentar de novo) e um link para o início.

test/, o ensaio

Os testes moram em src/test/, com a mesma árvore de src/: o do cliente está em src/test/shared/api/cliente.test.ts. Usam o Vitest para rodar e a Testing Library para usar a tela como uma pessoa a usa: procuram o botão pelo nome («Hacer el pedido», Fazer o pedido), não por uma classe de CSS. O princípio dela explica: «The more your tests resemble the way your software is used, the more confidence they can give you» [3].

Os testes falam com uma API de mentira, montada com MSW, que intercepta fetch sem mudar uma linha do código. Se um teste pedir algo que não foi declarado, falha: nenhum sai para a rede.

Um detalhe que não aparece na árvore: três tsconfig, um por programa (a aplicação, vite.config.ts no Node e os testes), e tsc -b revisa os três em modo estrito, que desde o TypeScript 6 vem ligado [9]. O tsconfig.json da raiz só os lista: ali, tsc --noEmit não revisa um único arquivo e sai no verde.

Quem vigia as fronteiras?

O ESLint, com um plugin que sabe qual pasta é qual. E um script que demonstra que ele vigia de verdade.

Para o TypeScript, import { TicketDelPedido } from "../../pedidos/components/TicketDelPedido" dentro do carrito é um import como qualquer outro. Para o Vite, também. O compilador revisa se os tipos batem, não quem é dono de quê.

Quem revisa isso é o eslint-plugin-boundaries. Em eslint.config.js, cada pasta de src/ é um «elemento» com um tipo (funcionalidad, pagina, ui, api), e embaixo vai quem pode importar quem. O que não está permitido está proibido:

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

De uma regra que nunca foi vista no vermelho não se sabe se existe. Por isso o template traz herramientas/probar-frontera.sh. Numa cópia temporária, ele faz um controle, que tem que passar limpo, e três violações plantadas: o carrito que importa o tíquete, um botão de ui que importa o cliente da API e um arquivo solto em src/. Cada violação plantada tem que compilar e construir, e o lint, falhar com um único erro da regra esperada no arquivo plantado, lido do relatório JSON do 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)

E se o script mentisse? Nós o sabotamos de cinco formas (a regra desligada, as funcionalidades autorizadas a se importar entre si, sem a regra de arquivos soltos, um cruzamento já escrito e sem dependências instaladas). Nas cinco vezes ele saiu com código 1. É o mesmo papel que o ArchUnit fez na entrega 6, com outra ferramenta.

O que medimos?

Tudo o que este texto afirma sobre o template saiu de rodá-lo, em 19 de novembro de 2026, no macOS com Node 26.13.1. No Linux, quem o rodou foi o CI do GitHub, no Ubuntu 26.04 com Node 26.13.0 e 26.13.1: 37 de 37, o mesmo orçamento de 100,14 kB e a fronteira que se sustenta. No Linux Mint não foi testado.

Os testes. npm run verificar roda cinco passos e para no primeiro que falhar: tipos, lint, formato, testes e build. Os testes terminam assim:

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

São 37 testes em 11 arquivos, contados duas vezes: no console e no relatório JSON do Vitest, que dá 37 37 0 (total, passaram, falharam). Contam-se no relatório e não no código de saída: um arquivo que não consegue importar algo sai como (0 test), e o total cai sem que nada fique vermelho.

O build. O que o navegador baixa:

O build. O que o navegador baixa
PedaçoTamanhoComprimido
O de entrada, que toda visita baixa318 kB100,5 kB
O cliente da API com zod, compartilhado85,5 kB24,9 kB
A tela de novo pedido3,1 kB1,5 kB
A tela do tíquete2,6 kB1,2 kB
Os estilos2,1 kB0,8 kB

Neste build, as duas páginas saem como chunks separados: NuevoPedidoPage pesa 3,12 kB e PedidoPage 2,62 kB. Uma rota nova deve conservar esse carregamento sob demanda; meça de novo, porque os chunks compartilhados podem mudar.

Estes números são um retrato do momento, não um orçamento. Uma aplicação que vai para produção precisa de um teto versionado que faça o build falhar, de dois builds idênticos e de uma esteira com lint, tipos, testes, build, Sonar, auditoria e varredura de segredos. Esta semente ainda mede; ao crescer, acrescente essas travas antes de tratar o tamanho como uma regra. O template já traz o teto (110 kB do pedaço de entrada), a auditoria e os dois builds; o Sonar e a varredura de segredos faltam, e o README diz isso.

O contrato, ao vivo. Subimos a API da entrega 6 (estructura-quarkus, commit 33e89f5) com jwebserver -b 127.0.0.1 -p 9090 -d "$PWD/ejemplo/inventario" e java -jar target/quarkus-app/quarkus-run.jar, na 8080. npm run contrato deu 4 de 4; sem a API, 4 no vermelho. Depois, npm run dev. Em desenvolvimento, o navegador pede tudo ao Vite e o Vite passa para a API o que começa com /v1 (o server.proxy de vite.config.ts [10]); para o navegador é uma única origem e não é preciso configurar CORS. Por esse caminho: o pedido foi criado (201), o tíquete dele foi lido e passou pelo esquema, e os três erros chegaram com o código e a frase fixa de cada um: SIN_EXISTENCIAS (409), PRODUCTO_NO_EXISTE (422) e PEDIDO_NO_ENCONTRADO (404). O detalhe que o servidor escreveu («De TAZA-01 se pidieron 4 y hay 3», ou seja, da TAZA-01 foram pedidas 4 e há 3) ficou no log dele, junto ao mesmo X-Request-ID que a tela mandou. Com a API desligada, o Vite responde 502 e a tela diz «Algo salió mal de nuestro lado. Intenta de nuevo.» (Algo deu errado do nosso lado. Tente de novo.), sem um único detalhe técnico.

As versões, medidas nesse dia com 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 e ESLint 10.15.0. O TypeScript 7 ainda «does not ship with an API» [4]: não expõe a API que o typescript-eslint usa para analisar TypeScript; por isso o template instala o TS 7 para o tsc e conserva o TS 6 sob o nome typescript para essa ferramenta, como recomenda o anúncio dele.

Quais são cinco erros frequentes?

Todos foram medidos no template. Os cinco passam por algum controle e falham em outro.

1. A funcionalidade que pega emprestadas as peças de outra

É o erro do Iván. Compila, constrói e passa nos testes, porque cada teste revisa a própria tela e nenhum revisa quem importa quem. No dia em que alguém muda a peça para a tela dele, a outra muda também. Como se evita: a regra do ESLint. Se as duas telas precisam da mesma coisa, a página junta as duas peças, ou o que é comum sobe para shared/ com um nome que diga o que faz. Se duas cópias mudam pela mesma razão, juntam-se já; se só se parecem, toleram-se enquanto cada uma mudar por conta própria, e na terceira a decisão se escreve, sem obrigação de subi-la.

2. O alias que o lint não vê

Muitos projetos escrevem @/features/pedidos/... em vez de ../../pedidos/.... Declara-se o alias em tsconfig e no Vite, compila e constrói. Mas, se o ESLint não sabe resolvê-lo, o plugin não sabe para que arquivo ele aponta. A documentação do plugin diz isso: por padrão, «non-relative imports that cannot be resolved are categorized as external» [5]. E o que é externo, como o React, não é revisado. Medido: com o alias, o carrito importou o tíquete de pedidos e o lint passou; o mesmo import com caminho relativo, no mesmo projeto, foi detido. Como se evita: o template usa caminhos relativos. Para quem quiser o alias, acrescente também eslint-import-resolver-typescript: com ele, o mesmo import é detido (medido). E acrescente ao script da fronteira uma violação plantada com alias, para que ele avise se um dia deixar de vê-lo.

3. O teste que ninguém roda

Escreve-se Boton.test.tsx junto a Boton.tsx, como em muitos tutoriais. Neste template, o Vitest só procura em src/test/ (por padrão procuraria no projeto todo, com **/*.{test,spec}.?(c|m)[jt]s?(x) [6]). Medido: um teste que sempre falha, escrito junto ao botão, deixou o total em 37 passed e o código de saída em 0. Como se evita: os testes vão em src/test/, e o CI do template traz um passo que fica vermelho se encontrar um arquivo de teste fora dali (testamos à mão, plantando um).

4. A tela em branco embaixo do cabeçalho

Põe-se o limite de erro na mesma rota que baixa o código da tela. Parece o lógico. Medido com React Router 8.5.2: se o código não puder ser baixado (uma conexão que cai, uma versão nova publicada enquanto a pessoa navegava), o erro fica registrado, mas a tela de reserva não aparece. Fica o cabeçalho e, embaixo, nada. Como se evita: o limite vai um nível acima, numa rota sem caminho próprio que envolve a que baixa o código. No template quem faz isso é conLimiteDeError, e o teste de rutas.test.tsx cuida disso: se o limite voltar para a mesma rota, ele fica vermelho (medido: 36 de 37).

5. Confiar no vite build para os tipos

O Vite constrói rápido porque não revisa tipos. A documentação dele diz: «Vite only performs transpilation on .ts files and does NOT perform type checking» [7]. Medido: com export const total: number = "cien", vite build saiu no verde e tsc -b no vermelho, com TS2322. Como se evita: npm run typecheck antes de construir, e no CI.

5. Confiar no vite build para os tipos
#ErroO que o deixa passarO que o detém
1Uma funcionalidade importa peças de outratsc, vite build, os testesA regra do ESLint
2Alias @/ sem resolver no ESLinttsc, vite build e o lintO resolver do TypeScript e uma violação plantada com alias
3Teste junto ao componenteO Vitest, que não o rodaTestes em src/test/ e o passo do CI
4Limite de erro na rota do lazytsc, o lint, um teste que não simule a falhaO limite um nível acima e o teste dele
5Erro de tiposvite buildtsc -b

Exercício: dá para pôr o formulário na tela do tíquete?

O exercício repete o que alguém fez no projeto do Iván, mostra que tudo passa menos o lint, e depois faz do jeito certo.

A loja pede algo razoável: que na tela do tíquete se possa fazer outro pedido ali mesmo, sem voltar ao início. É preciso ter Node 26.13 ou mais novo (node --version), Git 2.23 ou mais novo (por causa do git restore) e bash; uns 25 minutos. No Windows, use o WSL. O exercício completo foi testado no macOS.

Passo 1. Clone e confira que tudo está no verde.

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

Deve aparecer Tests 37 passed (37), depois o build e, no fim do script, ✅ frontera: se sostiene. Use este clone só para praticar: assim, toda mudança que aparecer nele é do exercício. No macOS, npm ci pode avisar que fsevents traz scripts de instalação sem aprovação: é um aviso, não um erro, e o passo 1 sai no verde sem eles.

Passo 2. Escreva primeiro o teste. Este diz o que a loja pediu: na tela do tíquete, além do tíquete, há um botão «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

Fica vermelho, e pela razão certa: Unable to find an accessible element with the role "button" and name "Hacer el pedido". O resumo diz Tests 1 failed | 37 passed (38).

Passo 3. Preveja, e depois caia na tentação. Quem pinta o tíquete é ConsultaDelPedido, em features/pedidos/. O mais rápido é pôr ali o formulário do carrito. Antes de fazer isso, anote: compila? Os testes passam? E o lint?

Abra src/features/pedidos/components/ConsultaDelPedido.tsx. Acrescente esta linha junto aos outros import:

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

E troque o caso "listo" por este:

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

Agora rode, um por um:

npm test
npm run typecheck
npm run build
npm run lint

Os testes dizem Tests 38 passed (38): o teste novo já passa. Os tipos e o build, sem um erro. O lint, não:

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

Repare no alCrear={() => {}}: a consulta do pedido não tem para onde mandar o cliente quando termina, porque navegar não é o trabalho dela. O código já estava dizendo que o formulário não morava ali.

Passo 4. Pergunte ao script.

bash herramientas/probar-frontera.sh

Fica vermelho sem passar do controle: ❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla del lint. É o controle trabalhando: não dá para demonstrar que o lint sabe falhar se o projeto já o tem falhando.

Passo 5. Desfaça só o que foi mexido, e faça na mesa. Antes, veja o que mudou:

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

Deve aparecer 1 file changed, 7 insertions(+), 1 deletion(-). Se aparecer algo mais, não é do exercício: guarde antes de seguir. Se só estiver o do exercício, restaure esse arquivo. O git restore só mexe nos caminhos indicados:

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

Agora sim: quem junta duas funcionalidades é a página. Escreva PedidoPage assim:

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

Tudo no verde: Tests 38 passed (38) e ✅ frontera: se sostiene. Agora alCrear tem, sim, algo a fazer: a página sabe para onde ir. E o git status mostra o trabalho feito, nada mais:

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

Como saber que deu certo: foram três desfechos. O teste vermelho no passo 2. Tudo verde menos o lint no passo 3, e o script vermelho no passo 4. E tudo verde no passo 5, com o mesmo teste pedido no começo. Se no passo 3 os tipos marcarem um erro, confira que o import ficou em cima, junto aos outros.

Para levar

Três perguntas para fazer ao projeto de React esta semana.

  1. Escolha um arquivo de src/ ao acaso. Quem o apagaria? Se a resposta for «ninguém» ou «depende», ele ainda não tem dono.
  2. Que componente é importado a partir de duas funcionalidades diferentes? grep -rn "from \"../../" src/features é um bom começo. Cada resultado que cruza para outra funcionalidade é um botão que pode mudar em duas telas.
  3. O que fica vermelho se alguém escrever esse cruzamento amanhã? Se a resposta for «nada», a estrutura do projeto é um costume, não uma regra.

O que deixam as sete entregas

Sete linguagens, sete templates, e a mesma pergunta: de quem é este arquivo e o que fica vermelho se eu o puser em outro lugar?

Começamos com Go e um padrão de pastas que não era padrão. Seguimos com Python, o pacote que passava na própria máquina e falhava instalado; com Rust e a função que ninguém conseguia testar; com TypeScript e o import que compilava e não iniciava. Depois montamos a mesma cozinha duas vezes, com Spring Boot e com Quarkus, e hoje o salão, com React.

As ferramentas mudaram a cada domingo. O que se repetiu foi isto:

  • Cada pasta tem um papel e um «nunca». Se não dá para dizer o que nunca vai numa pasta, a pasta não tem papel.
  • De uma regra que nunca foi vista no vermelho não se sabe se existe. Por isso cada template traz a própria fronteira que sabe falhar: um compilador, um ArchUnit ou um lint que fica vermelho com um erro plantado, e um controle que demonstra que não ficou vermelho por outra razão.
  • Conta-se no relatório, não no código de saída. No TypeScript, uma execução sem arquivos de teste saía com 0; no Quarkus, uma classe de testes que não iniciava deixava os testes dela como ignorados; hoje, um arquivo que não consegue importar sai como (0 test). Nas três vezes, o código de saída dizia que estava tudo bem.
  • Uma pasta nova tem que resolver um problema que já existe. Nenhum template traz o que ainda não dói, e cada README diz quando acrescentá-lo.

O Iván já não procura o botão numa pilha de oitenta arquivos. Procura a funcionalidade, e dentro encontra o botão.

O template e o curso

  • Template: github.com/HabilMX/estructura-react. Usa-se como template do GitHub ou se clona. O README explica cada pasta, a fronteira com a saída real, os erros medidos, o que não traz e as travas que faltam para produção, quando acrescentar cada coisa e como tirar o exemplo. docs/ARCHITECTURE.md traz a tabela de quem importa quem em uma folha. O código é MIT; o texto e as explicações são CC BY-SA 4.0.
  • Para vê-lo trabalhar com a cozinha: suba a API de estructura-quarkus (medida com o commit 33e89f5) como diz o README dela, na porta 8080; rode npm run contrato e depois npm run dev neste template. Abra http://localhost:5173/, peça duas TAZA-01 e veja o tíquete.
  • Versões: Node 26.13 ou mais novo; as demais, no README. Foi testado no macOS arm64 e, no CI do GitHub, no Ubuntu 26.04; no Linux Mint, ainda não.
  • Curso de React da Hábil: se os hooks, as rotas ou os testes com Testing Library forem novidade, comece por ali: Curso de React. E se as entregas 5 e 6 ainda não foram lidas, convém lê-las: esta dá por sabidos os papéis do restaurante.

Escrevo a partir do que vemos todos os dias na Hábil, onde construímos sistemas para bancos, seguradoras e empresas no México. Se no trabalho ou na faculdade aparecer um repositório em que ninguém sabe onde mexer, vamos conversar: habil.mx

O que a Hábil faz?

Ensinamos a programar com o mesmo que usamos para construir: código testado, explicado e aberto.

Esta série nasce do mesmo lugar que os nossos cursos. O Curso de React leva de um painel de uma peça só a um app de várias telas que se sustenta, e o publicamos aberto, com licença Creative Commons; a lição 0 monta o projeto com Vite, os três tsconfig e a estrutura por funcionalidade, a mesma base que o template deste artigo usa. E no catálogo há mais cursos de programação, gratuitos e com código testado e explicado passo a passo.

Veja o Curso de React e o catálogo de Cursos de programação.

Também construímos aplicativos web, mobile e desktop sob medida, com frontends organizados por funcionalidade, que podem ser mantidos e ampliados sem quebrar o que está ao lado, para bancos, seguradoras e empresas. Um frontend que já virou uma pilha de arquivos em que ninguém se atreve a mexer pode ser colocado em ordem sem parar a operação: veja Aplicativos web, mobile e desktop. Peça a primeira conversa, sem custo. Nela avaliamos se convém configurar o que a equipe já tem, usar um produto ou construir, e o que ela receberia em cada caso. Escreva para nós pelo WhatsApp.

Fontes consultadas em 19 de novembro de 2026. As citações em inglês são reproduzidas tal como estão.

Referências

  1. React, «File Structure» (perguntas frequentes da documentação legada do 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 do TypeScript, 8 de julho 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