Към съдържанието
Фронтенд20 мин

Структурата на един проект (7): бутонът, който се премести на два екрана

От · съосновател и Chief Executive Officer на Hábil ·

Екран на React с TypeScript и Vite, разделен по функционалност: къде живее всеки файл, какво спира ESLint и какво измерихме в шаблона.

Структурата на един проект · част 7 от 7 · React

Сценарий: героите и историята са измислени. Техническите данни и цитатите са с източник в края.

За 1 минута

  • Ресторантът от части 5 и 6 имаше кухня. Това е салонът: това, което вижда клиентът. Правилата са същите (всеки със своето, стрелките само в една посока); променя се как се разрязва проектът.
  • На сървъра се разрязва по слоеве: сервитьор, готвач, килер. На екрана се разрязва по функционалности: «да направиш поръчка» и «да видиш поръчката си» живеят всяка в своята папка, с всичко свое вътре.
  • Правилото, което решава: един файл живее там, където би се изтрил. Ако утре магазинът спре да продава през уеб, изтриваш една папка и нейната страница и нищо друго не се чупи.
  • Една функционалност не импортира частите на друга. TypeScript и Vite не го виждат: компилира се, изгражда се и тестовете минават. В шаблона го спира ESLint, а един скрипт доказва, че го спира.
  • Измерено в шаблона: 37 теста в зелено, прочетени от отчета; всеки екран пътува в собствено парче код (chunk) от 3 kB, а договорът с API-то от част 6 беше изпробван на живо.
  • За понеделник: потърси в своя проект компонент, който се импортира от две различни папки на функционалности. Това е бутонът, който ще се премести на два екрана.

В тази статия

  1. Какво се случи в петък в 17:40?
  2. Какво се променя и какво не?
  3. Къде живее всеки файл?
  4. Какво отива във всяка папка?
  5. Кой пази границите?
  6. Какво измерихме?
  7. Кои са пет чести грешки?
  8. Упражнение: можеш ли да сложиш формуляра на екрана с касовата бележка?
  9. Ключови изводи
  10. Какво оставят седемте части
  11. Шаблонът и курсът
  12. Какво прави Hábil?
  13. Източници

Какво се случи в петък в 17:40?

Иван премести един бутон на екрана с касовата бележка. В понеделник бутонът се беше преместил и на екрана за плащане.

Петък, 17:40. Трети етаж.

Задачата беше малка. Магазинът искаше бутона «Отпечатай бележката» горе, до номера на поръчката, а не чак долу, където никой не го виждаше. Иван отвори папката src/ на проекта на React и намери осемдесет файла на едно ниво: Ticket.tsx, Boton.tsx, api.ts, utils.ts, PaginaPago.tsx, useDatos.ts. Нито една папка не казваше кое на кого е.

Потърси бутона и го намери в Ticket.tsx. Качи го три реда нагоре. Пусна обичайното:

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

Всичко в зелено. Качи промяната и си тръгна.

Понеделник, 10:30.

Лусия му показа снимка на екрана, която беше изпратил магазинът. Беше екранът за плащане, този, който се вижда преди да платиш. Най-горе, до поръчка, която още не съществуваше, имаше бутон: «Отпечатай бележката».

— Една клиентка я отпечата и си тръгна — каза Лусия. — Помисли, че вече е платила.

Иван не беше пипал екрана за плащане. Лусия отвори терминала и написа едно-единствено търсене:

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

Два екрана ползваха един и същ Ticket. Някой, месеци по-рано, беше поискал да покаже обобщение на поръчката на екрана за плащане и вместо да направи свое, беше взел назаем касовата бележка от другия. Работеше. Никой не се оплака. Докато бележката не се промени заради своя екран, а другият се промени заедно с нея.

— Компилаторът не е виновен — каза Лусия. — За него това, че един екран ползва компонент на друг, е напълно наред. Въпросът е друг: чий е Ticket.tsx?

В API-то от част 6 Иван щеше да го знае за секунда. Тук нямаше пакети, само купчина.

— На екрана на поръчката — отговори той.

— Тогава, ако екранът на поръчката изчезне, какво става с PaginaPago.tsx?

— Чупи се.

— Ето го. Този файл не живее там, където би се изтрил.

Какво се променя и какво не?

Правилата на ресторанта не се променят. Променя се частта от ресторанта: от кухнята минаваме в салона.

В части 5 и 6 сглобихме кухнята на един магазин за поръчки: API, което приема поръчката, сготвя я и я записва. Тази част е салонът, това, което вижда клиентът: екранът, където прави поръчката си, и екранът, където вижда касовата си бележка. Шаблонът се казва estructura-react и говори с API-то от част 6.

Трите правила, с които затворихме част 5, са и тук:

  1. Всеки със своето. Бутонът не знае какво е поръчка; формулярът не знае, че екранът с касовата бележка съществува.
  2. Стрелките само в една посока. Страницата ползва функционалността; функционалността никога не ползва страницата.
  3. Това, което влиза, това, което се пази, и това, което излиза, са различни неща. Това, което API-то отговаря, се проверява при пристигане, преди да се нарисува.

Променя се как се разрязва проектът. В кухнята разрязахме по слоеве, като етажите на сграда: всичко за приемането в api, всичко за правилата в service. В салона се разрязва по функционалности, като отделите на магазин: всичко за «да направиш поръчка» в една папка, всичко за «да видиш поръчката си» в друга.

Защо друг разрез? Защото на един екран това, което се добавя и се изтрива, е цяла функционалност. Магазинът никога няма да ти каже «изтрий всички hook-ове»; ще ти каже «махни възможността да се поръчва през уеб».

Какво се променя и какво не?
В салонаПапкаКакво НИКОГА не прави
Всяка услуга в салона: да вземе поръчката, да подаде касовата бележкаfeatures/<nombre>/Да бърка в съседната услуга
Масата, където услугите се събират за един клиентpages/Да готви: нито извиквания към API-то, нито правила
Съдовете и приборите: служат за всичко и не знаят какво ястие носятshared/components/ui/Да знае какво е поръчка
Гишето към кухнятаshared/api/Да рисува нещо
Заведението: вратата, табелата и планът, ако нещо паднеapp/Бизнес правила
Репетицията преди отварянеtest/Да обслужва истински клиент

Старата документация на React казва, че React не налага папки, «React doesn’t have opinions on how you put files into folders», и споменава групиране «by feature or route» [1]. Ползвай го като отправна точка; конкретното правило на този шаблон е архитектурно решение и затова е добре нещо да го пази.

Къде живее всеки файл?

Там, където би се изтрил. Ако не можеш да отговориш кой би го изтрил, още не знаеш къде отива.

Това е дървото на шаблона, с това, което има значение за структурата:

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/

Изпробвай правилото с три файла:

  • TicketDelPedido.tsx. Ако магазинът махне екрана на поръчката, той си отива. Живее в features/pedidos/.
  • dinero.ts, който превръща сентавос в песос (47000 в $470.00). Ползват го касовата бележка и формулярът. Ако едното от двете си отиде, другото продължава да има нужда от него: не е на никое от тях. Живее в shared/lib/.
  • Boton.tsx. Ползват го всички и не знае нищо за бизнеса. Живее в shared/components/ui/.

С това правило Ticket.tsx на Иван имаше един-единствен собственик, екрана на поръчката. Екранът за плащане не можеше да го вземе назаем. Ако му трябваше обобщение, имаше два пътя и двата са в шаблона: да направи свое или една страница да събере двете части.

Какво отива във всяка папка?

Шест папки, всяка със своята роля и своето «никога».

features/, услугите в салона

Функционалност е нещо, което магазинът може да назове: carrito (да направиш поръчка) и pedidos (да видиш поръчка). Вътре — четири подпапки, и само тези, които са нужни:

  • components/: това, което се рисува.
  • hooks/: състоянието на екрана. usePedido знае дали поръчката се зарежда, дали е готова, дали не съществува или е имало грешка, и нищо повече.
  • services/: извикването към API-то. buscarPedido иска GET /v1/pedidos/{id}.
  • schemas/: формата на данните, написана със zod. Схемата върши две работи: проверява това, което пристига, и от нея излиза типът на 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>;

Защо да проверяваш това, което отговаря собственото ти API? Защото типовете на TypeScript не стигат до браузъра: ако API-то смени едно поле, екранът рисува undefined, без някой да предупреди. Схемата е поръчката, проверена на вратата.

Това семе учи на границата и на четирите състояния с две извиквания. В продуктов проект типовете на договора се генерират от OpenAPI, а отдалеченото състояние се управлява с кеш за отдалечено състояние (TanStack Query, SWR или друг). Тук ползваме схеми и един hook само защото учебното API още не публикува този договор; това е обявено ограничение, а не крайната цел.

Правилото «никога»: една функционалност не импортира нищо от друга. Нито компонент, нито hook, нито тип.

pages/, масата

По една страница на маршрут, и тя само събира. Това е цялата страница на поръчката:

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

Страницата за нова поръчка прави нещо по-фино. Формулярът на carrito не навигира: съобщава «създадох поръчката» чрез функция, която страницата му подава, alCrear, и страницата решава да отиде при касовата бележка. Така carrito не знае, че екранът с касовата бележка съществува.

Правилото «никога»: една страница не вика API-то, не пази правила и не пише свободен HTML. Тя композира.

За това приложение ползваме features/ и shared/: страницата композира части от своята функционалност и от ui директно. В по-голям frontend може да си струва междинен слой от секции; тук това би била една папка в повече.

shared/components/ui/, съдовете

Boton, Campo, Aviso и Pagina. Това са части, които служат на всеки екран, защото не знаят нищо за бизнеса. Campo свързва своя етикет и своята грешка, за да ги обяви екранен четец; не знае, че е имейл.

Няма index.ts, който да реекспортира папката: всеки импорт казва от кой файл идва. Vite моли тези файлове да се избягват, защото карат да се изтеглят всички части, за да се ползва една, «loading more files than required on the initial page load» [8].

Правилото «никога»: една част от ui не вика API-то и не познава нито една функционалност.

shared/api/, гишето към кухнята

cliente.ts е единственото място в проекта, което вика fetch. Затова може да прави три неща, които никой друг не трябва да помни:

  • Лимит за време за всяко извикване: 8 секунди, с AbortSignal.timeout. Ако API-то не отговори, екранът го казва, вместо да остане да зарежда.
  • Идентификатор във всяко извикване, X-Request-ID, който сървърът от част 6 записва в дневника си.
  • Едно фиксирано изречение за всяка грешка. API-то отговаря с Problem Details и неговото поле error_code казва коя е била (SIN_EXISTENCIAS). Клиентът търси този код в таблица и показва неговото изречение: «No hay piezas suficientes de uno de los productos.» (Няма достатъчно бройки от един от продуктите.) Текстът на сървъра никога не стига до екрана: може да носи подробности, които човекът няма защо да вижда.

Правилото «никога»: гишето не рисува нищо и не знае коя функционалност го ползва.

app/, заведението

Тук се монтират маршрутите, заглавната лента и планът, ако нещо падне. Две решения имат значение. Първото: всеки екран пътува в собствено парче код и се изтегля едва когато някой го посети. Това е отложеното зареждане (lazy).

Второто: всеки екран има своя граница за грешки. Граница за грешки (Error Boundary) е компонент, който улавя срива на това, което е вътре в него, и рисува нещо друго на негово място. Документацията на React го казва за отложеното зареждане: ако обещанието, което изтегля кода, се провали, «React will throw the rejection reason for the nearest Error Boundary to handle» [2]. В шаблона, ако един екран не може да се изтегли или гръмне при рисуване, заглавната лента остава и се появяват «No pudimos mostrar esta pantalla.» (Не успяхме да покажем този екран.), бутон «Reintentar» (Опитай отново) и връзка към началото.

test/, репетицията

Тестовете живеят в src/test/, със същото дърво като src/: този на клиента е в src/test/shared/api/cliente.test.ts. Ползват Vitest, за да се пускат, и Testing Library, за да ползват екрана така, както го ползва човек: търсят бутона по името му («Hacer el pedido», тоест «Направи поръчката»), а не по CSS клас. Принципът ѝ го обяснява: «The more your tests resemble the way your software is used, the more confidence they can give you» [3].

Тестовете говорят с фалшиво API, сглобено с MSW, което прихваща fetch, без да променя и ред от кода. Ако тест поиска нещо, което не е обявено, пада: нито един не излиза в мрежата.

Една подробност, която не се вижда в дървото: три tsconfig, по един на програма (приложението, vite.config.ts в Node и тестовете), а tsc -b проверява трите в строг режим, който от TypeScript 6 е включен по подразбиране [9]. tsconfig.json в корена само ги изброява: там tsc --noEmit не проверява нито един файл и излиза в зелено.

Кой пази границите?

ESLint, с плъгин, който знае коя папка каква е. И скрипт, който доказва, че наистина пази.

За TypeScript import { TicketDelPedido } from "../../pedidos/components/TicketDelPedido" вътре в carrito е импорт като всеки друг. За Vite — също. Компилаторът проверява дали типовете пасват, а не кой на какво е собственик.

Това го проверява eslint-plugin-boundaries. В eslint.config.js всяка папка от src/ е «елемент» с тип (funcionalidad, pagina, ui, api), а отдолу стои кой кого може да импортира. Което не е позволено, е забранено:

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

За правило, което никога не е видяно в червено, не се знае дали съществува. Затова шаблонът носи herramientas/probar-frontera.sh. Във временно копие той прави контрола, която трябва да мине чисто, и три засети нарушения: carrito, който импортира касовата бележка, бутон от ui, който импортира клиента на API-то, и свободен файл в src/. Всяко засято нарушение трябва да се компилира и да се изгради, а линтът — да се провали с една-единствена грешка от очакваното правило в засетия файл, прочетена от JSON отчета на 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)

А ако скриптът лъже? Саботирахме го по пет начина (изключено правило, функционалности, на които е разрешено да се импортират една друга, без правилото за свободни файлове, вече написано пресичане и без инсталирани зависимости). И петте пъти излезе с код 1. Това е същата роля, която изигра ArchUnit в част 6, с друг инструмент.

Какво измерихме?

Всичко, което този текст твърди за шаблона, идва от пускането му, на 19 ноември 2026 г., в macOS с Node 26.13.1. В Linux го пусна CI на GitHub, в Ubuntu 26.04 с Node 26.13.0 и 26.13.1: 37 от 37, същият бюджет от 100,14 kB и границата, която се държи. В Linux Mint не е тестван.

Тестовете. npm run verificar пуска пет стъпки и спира на първата, която се провали: типове, линт, формат, тестове и билд. Тестовете завършват така:

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

Това са 37 теста в 11 файла, преброени два пъти: в конзолата и в JSON отчета на Vitest, който дава 37 37 0 (общо, минали, паднали). Броят се в отчета, а не в кода за изход: файл, който не успява да импортира нещо, излиза като (0 test), и общият брой пада, без нищо да стане червено.

Билдът. Това, което изтегля браузърът:

Билдът. Това, което изтегля браузърът
ПарчеРазмерКомпресиран
Входното, което изтегля всяко посещение318 kB100,5 kB
Клиентът на API-то със zod, споделен85,5 kB24,9 kB
Екранът за нова поръчка3,1 kB1,5 kB
Екранът с касовата бележка2,6 kB1,2 kB
Стиловете2,1 kB0,8 kB

В този билд двете страници излизат като отделни chunks: NuevoPedidoPage тежи 3,12 kB, а PedidoPage — 2,62 kB. Нов маршрут трябва да запази това отложено зареждане; измери отново, защото споделените chunks могат да се променят.

Тези цифри са снимка на момента, а не бюджет. Приложение, което отива в продукция, има нужда от версиониран таван, който да проваля билда, два идентични билда и pipeline с линт, типове, тестове, билд, Sonar, одит и претърсване за тайни. Това семе засега мери; когато порасне, добави тези предпазни мерки, преди да третираш размера като правило. Шаблонът вече носи тавана (110 kB за входното парче), одита и двата билда; Sonar и претърсването за тайни липсват и README-то го казва.

Договорът, на живо. Вдигнахме API-то от част 6 (estructura-quarkus, commit 33e89f5) с jwebserver -b 127.0.0.1 -p 9090 -d "$PWD/ejemplo/inventario" и java -jar target/quarkus-app/quarkus-run.jar, на порт 8080. npm run contrato даде 4 от 4; без API-то — 4 в червено. После npm run dev. При разработка браузърът иска всичко от Vite, а Vite предава на API-то това, което започва с /v1 (server.proxy във vite.config.ts [10]); за браузъра това е един-единствен произход (origin) и не е нужно да се настройва CORS. По този път: поръчката се създаде (201), касовата ѝ бележка се прочете и мина схемата, а трите грешки пристигнаха със своя код и своето фиксирано изречение: SIN_EXISTENCIAS (409), PRODUCTO_NO_EXISTE (422) и PEDIDO_NO_ENCONTRADO (404). Подробността, която написа сървърът («De TAZA-01 se pidieron 4 y hay 3», тоест «От TAZA-01 са поискани 4, а има 3»), остана в неговия дневник, до същия X-Request-ID, който изпрати екранът. С изключено API Vite отговаря 502, а екранът казва «Algo salió mal de nuestro lado. Intenta de nuevo.» (Нещо се обърка от наша страна. Опитай отново.), без нито една техническа подробност.

Версиите, измерени този ден с 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 и ESLint 10.15.0. TypeScript 7 все още «does not ship with an API» [4]: не предоставя API-то, което typescript-eslint ползва, за да анализира TypeScript; затова шаблонът инсталира TS 7 за tsc и запазва TS 6 под името typescript за този инструмент, както препоръчва обявата му.

Кои са пет чести грешки?

Всички са измерени в шаблона. И петте минават някоя проверка и се провалят на друга.

1. Функционалността, която взема назаем частите на друга

Това е грешката на Иван. Компилира се, изгражда се и тестовете минават, защото всеки тест проверява своя екран и никой не проверява кой кого импортира. В деня, когато някой промени частта заради своя екран, другият също се променя. Как се избягва: правилото на ESLint. Ако двата екрана имат нужда от едно и също, страницата събира двете части или общото се качва в shared/ с име, което казва какво прави. Ако две копия се променят по една и съща причина, се обединяват веднага; ако само си приличат, се търпят, докато всяко се променя само за себе си, а при третото решението се записва, без задължение общото да се качва.

2. Псевдонимът, който линтът не вижда

Много проекти пишат @/features/pedidos/... вместо ../../pedidos/.... Обявяваш го в tsconfig и във Vite, компилира се и се изгражда. Но ако ESLint не знае как да го разреши, плъгинът не знае към кой файл сочи. Документацията му го казва: по подразбиране «non-relative imports that cannot be resolved are categorized as external» [5]. А външното, като React, не се проверява. Измерено: с псевдонима carrito импортира касовата бележка от pedidos и линтът мина; същият импорт с относителен път, в същия проект, беше спрян. Как се избягва: шаблонът ползва относителни пътища. Ако искаш псевдонима, добави и eslint-import-resolver-typescript: с него същият импорт се спира (измерено). И добави към скрипта за границата едно засято нарушение с псевдоним, за да те предупреди, ако един ден престане да го вижда.

3. Тестът, който никой не пуска

Пишеш Boton.test.tsx до Boton.tsx, както в много уроци. В този шаблон Vitest търси само в src/test/ (по подразбиране би търсил в целия проект, с **/*.{test,spec}.?(c|m)[jt]s?(x) [6]). Измерено: тест, който винаги пада, написан до бутона, остави общия брой на 37 passed, а кода за изход — на 0. Как се избягва: тестовете отиват в src/test/, а CI на шаблона носи стъпка, която става червена, ако намери тестов файл извън тази папка (изпробвахме го на ръка, като засяхме един).

4. Празният екран под заглавната лента

Слагаш границата за грешки на същия маршрут, който изтегля кода на екрана. Изглежда логично. Измерено с React Router 8.5.2: ако кодът не може да се изтегли (връзка, която прекъсва, нова версия, публикувана, докато човекът е навигирал), грешката остава записана, но резервният екран не се появява. Остава заглавната лента, а под нея — нищо. Как се избягва: границата отива едно ниво по-горе, в маршрут без собствен път, който обгръща този, който изтегля кода. В шаблона това го прави conLimiteDeError, а тестът в rutas.test.tsx го пази: ако върнеш границата на същия маршрут, става червен (измерено: 36 от 37).

5. Да се довериш на vite build за типовете

Vite изгражда бързо, защото не проверява типове. Документацията му го казва: «Vite only performs transpilation on .ts files and does NOT perform type checking» [7]. Измерено: с export const total: number = "cien", vite build излезе в зелено, а tsc -b — в червено, с TS2322. Как се избягва: npm run typecheck преди билда, и в CI.

5. Да се довериш на vite build за типовете
#ГрешкаКакво я пропускаКакво я спира
1Една функционалност импортира части на другаtsc, vite build, тестоветеПравилото на ESLint
2Псевдоним @/, който ESLint не разрешаваtsc, vite build и линтътResolver-ът за TypeScript и едно засято нарушение с псевдоним
3Тест до компонентаVitest, който не го пускаТестове в src/test/ и стъпката в CI
4Граница за грешки на маршрута с lazytsc, линтът, тест, който не симулира сриваГраницата едно ниво по-горе и нейният тест
5Грешка в типоветеvite buildtsc -b

Упражнение: можеш ли да сложиш формуляра на екрана с касовата бележка?

Ще направиш това, което някой направи в проекта на Иван, ще видиш, че всичко минава освен линта, и после ще го направиш както трябва.

Магазинът иска нещо разумно: на екрана с касовата бележка да може да се направи още една поръчка на място, без връщане в началото. Трябват ти Node 26.13 или по-нов (node --version), Git 2.23 или по-нов (заради git restore) и bash; около 25 минути. В Windows ползвай WSL. Цялото упражнение е тествано в macOS.

Стъпка 1. Клонирай и провери, че всичко е зелено.

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

Трябва да видиш Tests 37 passed (37), после билда и, в края на скрипта, ✅ frontera: se sostiene. Ползвай този клонинг само за упражнение: така всяка промяна, която видиш в него, е от упражнението. В macOS npm ci може да предупреди, че fsevents носи инсталационни скриптове без одобрение: това е предупреждение, а не грешка, и стъпка 1 излиза в зелено и без тях.

Стъпка 2. Първо напиши теста. Той казва това, което магазинът поиска: на екрана с касовата бележка, освен бележката, има бутон «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

Става червен, и то по правилната причина: Unable to find an accessible element with the role "button" and name "Hacer el pedido". Обобщението казва Tests 1 failed | 37 passed (38).

Стъпка 3. Предскажи, а после се поддай на изкушението. Касовата бележка я рисува ConsultaDelPedido, в features/pedidos/. Най-бързото е да сложиш там формуляра на carrito. Преди да го направиш, запиши си: компилира ли се? Минават ли тестовете? А линтът?

Отвори src/features/pedidos/components/ConsultaDelPedido.tsx. Добави този ред до другите import:

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

И смени случая "listo" с този:

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

Сега пусни, едно по едно:

npm test
npm run typecheck
npm run build
npm run lint

Тестовете казват Tests 38 passed (38): твоят вече минава. Типовете и билдът — без нито една грешка. Линтът — не:

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

Обърни внимание на alCrear={() => {}}: справката за поръчката няма къде да изпрати клиента, когато приключи, защото навигирането не е нейна работа. Кодът вече ти казваше, че формулярът не живее там.

Стъпка 4. Попитай скрипта.

bash herramientas/probar-frontera.sh

Става червен, без да мине контролата: ❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla del lint. Това е контролата в действие: не може да докаже, че линтът може да се провали, ако проектът ти вече го проваля.

Стъпка 5. Върни само това, което пипна, и го направи на масата. Първо виж какво се промени:

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

Трябва да видиш 1 file changed, 7 insertions(+), 1 deletion(-). Ако видиш нещо друго, то е твое: запази го, преди да продължиш. Ако е само това от упражнението, върни този файл. git restore пипа само пътищата, които му дадеш:

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

Сега вече: този, който събира две функционалности, е страницата. Напиши PedidoPage така:

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

Всичко в зелено: Tests 38 passed (38) и ✅ frontera: se sostiene. Сега alCrear вече има какво да прави: страницата знае къде да отиде. А git status показва твоята работа и нищо друго:

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

Как разбираш, че си го направил добре: видя три изхода. Червения тест в стъпка 2. Всичко зелено освен линта в стъпка 3 и червения скрипт в стъпка 4. И всичко зелено в стъпка 5, със същия тест, който поиска в началото. Ако в стъпка 3 типовете покажат грешка, провери дали import е останал горе, до другите.

Ключови изводи

Три въпроса, които да зададеш на своя проект на React тази седмица.

  1. Избери произволен файл от src/. Кой би го изтрил? Ако отговорът е «никой» или «зависи», той още няма собственик.
  2. Кой компонент се импортира от две различни функционалности? grep -rn "from \"../../" src/features е добро начало. Всеки резултат, който пресича към друга функционалност, е бутон, който може да се премести на два екрана.
  3. Какво става червено, ако някой напише това пресичане утре? Ако отговорът е «нищо», структурата на проекта ти е навик, а не правило.

Какво оставят седемте части

Седем езика, седем шаблона и един и същ въпрос: чий е този файл и какво става червено, ако го сложа другаде?

Започнахме с Go и един стандарт за папки, който не беше стандарт. Продължихме с Python, пакета, който минаваше на твоята машина и гърмеше след инсталиране; с Rust и функцията, която никой не можеше да тества; с TypeScript и импорта, който се компилираше, но не тръгваше. После сглобихме една и съща кухня два пъти, със Spring Boot и с Quarkus, а днес — салона, с React.

Инструментите се сменяха всяка неделя. Това, което се повтори, беше следното:

  • Всяка папка има роля и едно «никога». Ако не можеш да кажеш какво никога не отива в една папка, папката няма роля.
  • За правило, което никога не е видяно в червено, не се знае дали съществува. Затова всеки шаблон носи своята граница, която може да се провали: компилатор, ArchUnit или линт, който става червен при засята грешка, и контрола, която доказва, че не е станал червен по друга причина.
  • Брои се в отчета, а не в кода за изход. В TypeScript пускане без тестови файлове излизаше с 0; в Quarkus тестов клас, който не стартираше, оставяше тестовете си като пропуснати; днес файл, който не успява да импортира, излиза като (0 test). И трите пъти кодът за изход казваше, че всичко е наред.
  • Една нова папка трябва да решава проблем, който вече имаш. Нито един шаблон не носи това, което още не боли, и всяко README казва кога да го добавиш.

Иван вече не търси бутона в купчина от осемдесет файла. Търси функционалността и вътре намира бутона.

Шаблонът и курсът

  • Шаблон: github.com/HabilMX/estructura-react. Ползва се като шаблон в GitHub или се клонира. README-то обяснява всяка папка, границата с реалния ѝ изход, измерените грешки, какво не включва и предпазните мерки, които му липсват за продукция, кога да се добави всяко нещо и как да се махне примерът. docs/ARCHITECTURE.md носи таблицата кой кого импортира на един лист. Кодът е под MIT; текстът и обясненията — под CC BY-SA 4.0.
  • За да го видиш как работи с кухнята: вдигни API-то от estructura-quarkus (измерено с неговия commit 33e89f5), както казва неговото README, на порт 8080; пусни npm run contrato, а после npm run dev в този шаблон. Отвори http://localhost:5173/, поръчай две TAZA-01 и виж касовата си бележка.
  • Версии: Node 26.13 или по-нов; останалите са в README-то. Тествано в macOS arm64 и, в CI на GitHub, в Ubuntu 26.04; в Linux Mint — още не.
  • Курсът по React на Hábil: ако hook-овете, маршрутите или тестовете с Testing Library са нови за теб, започни оттам: Курс по React. А ако не си чел части 5 и 6, добре е да ги прочетеш: тази приема ролите в ресторанта за известни.

Пиша от това, което виждаме всеки ден в Hábil, където изграждаме системи за банки, застраховане и компании в Мексико. Ако в работата или в университета ти и колегите ти попаднете на хранилище, за което никой не знае откъде да го хване, да поговорим: habil.mx

Какво прави Hábil?

Учим на програмиране със същото, с което изграждаме: тестван, обяснен и отворен код.

Тази поредица идва от същото място като нашите курсове. Курсът по React води от табло от едно парче до приложение с няколко екрана, което издържа, и го публикуваме отворено, с лиценз Creative Commons; урок 0 изгражда проекта с Vite, трите му tsconfig и структурата по функционалност — същата основа, която използва шаблонът от тази статия. А в каталога има още курсове по програмиране, безплатни и с тестван и обяснен стъпка по стъпка код.

Разгледай Курса по React и каталога Курсове по програмиране.

Също така изграждаме уеб, мобилни и десктоп приложения по поръчка, с frontend, подреден по функционалности, който може да се поддържа и да расте, без да чупи съседното, за банки, застраховане и компании. Ако frontend-ът ти вече е купчина файлове, които никой не смее да премести, може да се подреди, без да се спира дейността: разгледай Уеб, мобилни и десктоп приложения. Поискай първи разговор, без заплащане. В него преглеждаме дали си струва да се настрои това, което екипът ти вече има, да се ползва продукт или да се изгради, и какво би получил екипът във всеки случай. Пиши ни в WhatsApp.

Източниците са проверени на 19 ноември 2026 г. Цитатите на английски са възпроизведени дословно.

Източници

  1. React, «File Structure» (често задавани въпроси от старата документация на 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», блогът на TypeScript, 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

Вашата дейност среща ли тези предизвикателства?

Да обсъдим вашия проект

Предпочитате имейл? Пишете ни на hola@habil.mx