Анатомия React-проекта

что откуда берётся и почему файлов так много

Что это

React-проект выглядит пугающе: два десятка файлов в корне, папка node_modules на сотни мегабайт, конфиги инструментов, о которых ты не слышал. При этом твоего кода — одна папка.

Статья раскладывает это по полкам, чтобы в незнакомом проекте не искать точку входа полчаса.

Как выглядит в коде

weather-app/
├── node_modules/        библиотеки — не читать, не коммитить
├── public/              файлы, которые отдаются как есть
├── src/                 ← твой код, только он
│   ├── main.tsx         точка входа: монтирует приложение
│   ├── App.tsx          корневой компонент
│   ├── components/      компоненты
│   │   └── CityCard.tsx
│   ├── hooks/           свои хуки
│   ├── api/             запросы к серверу
│   └── types.ts         общие типы
├── index.html           страница, в которую всё вставляется
├── package.json         зависимости и команды
├── package-lock.json    точные версии — коммитить
├── tsconfig.json        настройки TypeScript (статья 9.3)
├── vite.config.ts       настройки сборщика
└── .env                 секреты — в .gitignore (статья 5.7)

Читать надо только src/. Всё остальное — обвязка.

Точка входа

import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(<App />);

Три строки, и в них вся связь между HTML и React: взять элемент #root из index.html и нарисовать в нём приложение. Дальше весь интерфейс рисует React, а index.html больше не меняется.

Восклицательный знак после getElementById — это as-подобное утверждение «элемент точно есть» (статья 9.5). Здесь оно оправдано: если #root нет, приложение всё равно не запустится.

Что такое сборщик

Браузер не понимает ни JSX, ни TypeScript, ни импорты из node_modules. Сборщик (чаще всего Vite) превращает всё это в обычный JavaScript.

Отсюда две команды, которые встречаются в каждом проекте:

npm run dev     # режим разработки: правка видна сразу
npm run build   # сборка в папку dist/ для выкладки

Что именно они делают — написано в package.json, в разделе scripts. Это первое место, куда стоит заглянуть в незнакомом проекте: там список всего, что с ним можно делать.

package.json

{
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "lint": "eslint ."
  },
  "dependencies": {
    "react": "^19.3.1",
    "react-dom": "^19.3.1"
  },
  "devDependencies": {
    "typescript": "^5.9.0",
    "vite": "^7.1.0"
  }
}

Про ^: знак означает «эта версия или новее, но в пределах мажорной». Поэтому у тебя и на сервере могут встать разные версии — и именно от этого защищает package-lock.json, который фиксирует точные. Его коммитят всегда (статья 5.6).

Как сказать ИИ

Покажи содержимое scripts из package.json и объясни,
что делает каждая команда. Одной строкой на команду.

Я открыл этот проект впервые. С каких трёх файлов в src
начать чтение, чтобы понять, как он устроен?

Добавь компонент CityCard в src/components/.
Структуру проекта не меняй, новых зависимостей не добавляй.

На что смотреть

node_modules в git. Сотни мегабайт чужого кода в репозитории. Проверяется наличием строки в .gitignore.

Нет package-lock.json. Версии не зафиксированы, и у тебя с сервером встанет разное.

Всё в одном App.tsx. Файл на тысячу строк вместо компонентов. Работать будет, менять — тяжело, и ИИ не сможет править часть, не задевая остальное.

Секреты в коде фронтенда. Важное отличие от бэкенда: всё, что попало в сборку, видно пользователю. Переменная VITE_API_KEY окажется в коде страницы. Настоящие ключи держат на сервере, а фронтенд обращается к своему бэкенду (статья 7.8).

Смесь .js и .tsx. Переход на TypeScript на полпути: в .js проверок нет.

Шпаргалка