Как собрать и запустить React-приложение

Введение

React стал одной из самых популярных JavaScript-библиотек для построения пользовательский интерфейсов. Однако запуск своего первого приложения зачастую вызывает вопросы: с чего начинать, какие инструменты использовать, как управлять процессом сборки, чем отличаются dev- и production-режимы, и какие подводные камни могут встретиться на этом пути.

В этой статье я подробно рассмотрю все этапы: от создания базового проекта до настройки и сборки оптимизированной версии приложения для публикации. Вы узнаете, как запустить ваше React-приложение локально и подготовить его к запуску на сервере.

Как создать новый React-проект

Использование Create React App (CRA)

Создание нового React-приложения проще всего начать с официального инструмента Create React App (CRA). Он сразу предлагает все необходимые настройки для разработки и сборки вашего проекта.

Установка Node.js и NPM

Для начала работы потребуется установленный Node.js вместе с менеджером пакетов npm или yarn. Node.js можно скачать с официального сайта (nodejs.org). После установки убедитесь, что команды работают:

node -v   # Показывает версию Node.js
npm -v    # Показывает версию npm

Инициализация проекта

Теперь вы можете создать новый проект командой:

npx create-react-app my-app
# или, если используете yarn:
# yarn create react-app my-app

• my-app — название вашей новой папки с проектом.
• npx — утилита, поставляемая с npm начиная с версии 5.2, позволяет запускать пакеты без их установки глобально.
• После выполнения команды в директории появится папка my-app с базовой структурой проекта.

Структура проекта

Давайте посмотрим, что находится внутри созданного каталога:

• public/ — здесь лежат статические файлы, корневой HTML-файл (index.html)
• src/ — основной исходный код приложения, JSX-компоненты, стили, тесты
• package.json — содержит список зависимостей, скрипты для запуска и сборки
• node_modules/ — устанавливаются автоматически, содержат все зависимости проекта

Сборка и запуск React-приложения - это важный этап разработки, который позволяет превратить исходный код в готовое к использованию приложение. Понимание того, как работает процесс сборки, и как правильно запускать приложение, необходимо для успешного развертывания. Если вам нужна подробная информация о сборке и запуске React-приложений — приходите на наш большой курс Основы React, React Router и Redux Toolkit. На курсе 177 уроков и 17 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Запуск React-приложения в режиме разработки

Как работает dev-сервер

Dev-сервер — это встроенное в CRA средство для локального запуска приложения. Он предоставляет быстрый запуск, автоматическую перезагрузку при изменениях в коде и вспомогательные инструменты отладки.

Команда для запуска

Перейдите в папку с проектом и выполните:

cd my-app
npm start
# или:
# yarn start

После этого вы увидите сообщение в консоли и сможете открыть приложение по адресу http://localhost:3000:

Compiled successfully!

You can now view my-app in the browser.

  Local:            http://localhost:3000
  On Your Network:  http://192.168.1.X:3000

• Любые изменения в файлах src/ автоматически приведут к пересборке и обновлению страницы в браузере, не теряя состояние приложения.

Особенности dev-режима

• Dev-сервер не оптимизирует код, чтобы ускорить сборку.
• Ошибки отображаются прямо в браузере («red box»).
• В dev-режиме есть карты исходников (source maps), чтобы вам было проще находить место ошибки в исходном коде.

Сборка production-версии React-приложения

Чем отличается production-режим от dev-режима

Production-режим — это оптимизированная версия приложения для реального использования пользователями. В ней:

• Код минифицирован и сжат.
• Удалены все отладочные сообщения и лишние проверки.
• Файлы подготовлены для эффективной отдачи сервером.

Команда сборки

Для создания production-сборки выполните:

npm run build
# или:
# yarn build

• Эта команда генерирует папку build/ (или dist/ у некоторых шаблонов), где будут лежать статические файлы приложения.

В структуре вы найдете:

• index.html — основной HTML-файл
• static/js — минифицированные JS-бандлы
• static/css — минифицированные CSS-файлы
• другие статические ассеты (media/, картинки и шрифты)

Как проверить production-сборку локально

Папку build/ можно раздать любым статическим сервером. Например, воспользуйтесь пакетом serve:

npm install -g serve
serve -s build

• Приложение будет доступно локально по адресу, например, http://localhost:5000.

Эта команда имитирует работу настоящего продакшн-сервера и позволяет убедиться, что всё работает корректно даже без node.js на сервере.

Какие файлы выкладывать на сервер

На сервере размещайте только содержимое папки build/. Весь исходный код (папка src/, директория node_modules/ и пр.) не требуется на сервере. Сервер должен уметь отдавать:

• index.html — как точку входа для всех маршрутов (настраивается через web-сервер типа nginx, Apache или Netlify)
• Статические ассеты — JS, CSS, медиафайлы из папки build/static/

Ручная настройка сборки (webpack, Vite, Parcel и другие альтернативы)

Когда нужна самостоятельная сборка

Иногда стандартные настройки CRA недостаточны: вам нужны определенные плагины, особая структура каталогов, продвинутые возможности или сверхминимальный бандл. В таких случаях разумно взять другой инструмент — например, Webpack или Vite — и самостоятельно описать процесс сборки.

Базовый пример конфигурации webpack

Покажу пример минимальной настройки для создания React-приложения вручную.

1. Инициализация проекта:

mkdir manual-react
cd manual-react
npm init -y
npm install react react-dom
npm install --save-dev webpack webpack-cli babel-loader @babel/core @babel/preset-env @babel/preset-react html-webpack-plugin webpack-dev-server

2. Создание структуры каталогов:

• src/index.js
• public/index.html
• webpack.config.js

3. Пример webpack.config.js:

// webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin')
const path = require('path')

module.exports = {
  entry: './src/index.js',   // Точка входа приложения
  output: {
    path: path.resolve(__dirname, 'dist'), // Папка для сборки
    filename: 'bundle.js',                 // Имя итогового файла
    clean: true,                           // Очистка папки перед сборкой
  },
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,              // Обработка js/jsx через Babel
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader'
        },
      },
    ],
  },
  resolve: {
    extensions: ['.js', '.jsx'],         // Позволяет импортировать .js и .jsx без расширения
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html',    // Использовать свой HTML-шаблон
    }),
  ],
  devServer: {
    static: {
      directory: path.join(__dirname, 'public'), // Статические файлы
    },
    compress: true,
    port: 3000,                         // Порт для dev-сервера
    hot: true,                          // Автоперезагрузка при изменениях
    historyApiFallback: true,           // Поддержка React Router и client-side routing
  },
}

4. Настройка Babel: создайте .babelrc в корне проекта:

{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}

5. Добавьте скрипты в package.json:

{
  "scripts": {
    "start": "webpack serve --mode development",
    "build": "webpack --mode production"
  }
}

6. Теперь можно запустить dev-сервер:

npm start

• И собрать оптимизированную версию:

npm run build

Обратите внимание, как вручную настраиваются все этапы: точка входа, шаблон HTML, обработка JSX через Babel, статические ассеты и девсервер.

Vite как современная альтернатива

Vite — это легковесный и очень быстрый билдер для современных front-end проектов. Его использование похоже на CRA:

npm create vite@latest my-vite-app -- --template react
cd my-vite-app
npm install
npm run dev

• Для сборки production-версии выполните:

npm run build

В каталоге dist/ появятся собранные файлы, готовые для публикации на сервере.

Переменные окружения и дополнительные настройки

Использование переменных окружения

В React-проектах часто используют .env файлы для передачи конфигурации на этапе сборки. Например, чтобы описать адрес API, токены, пути и другие значения, варьирующиеся между dev/production серверами.

Как добавить переменные окружения

Создайте файл .env в корне проекта со строками:

REACT_APP_API_URL=https://api.example.com
REACT_APP_OTHER_VALUE=some_value

• Все переменные должны начинаться с REACT_APP_, чтобы CRA и Vite их "увидели" в процессе сборки.

Используйте их в коде так:

const apiUrl = process.env.REACT_APP_API_URL

• Переменные «зашиваются» в итоговый бандл во время сборки, скрытых или приватных данных в них быть не должно.

Использование alias и абсолютных импортов

Для удобства импорта компонентов можно в webpack или Vite настроить alias, чтобы писать короткие и понятные пути импорта.

В webpack

В файле webpack.config.js добавьте:

resolve: {
  alias: {
    '@components': path.resolve(__dirname, 'src/components/'),
  }
}

Теперь компонент можно импортировать как:

import Button from '@components/Button'

В Vite

В файле vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@components': path.resolve(__dirname, 'src/components/'),
    }
  },
})

Работа с маршрутизацией (React Router) в production-сборке

Маршрутизация внутри SPA базируется на client-side routing: все URL-ы должны обслуживаться единым HTML-файлом. Для этого требуется специальная настройка на сервере:

• В дев-сервере CRA и Vite все это настроено автоматически.
• На production-сервере (например, nginx) нужно сделать так, чтобы любой путь возвращал index.html, чтобы React сам справлялся с маршрутами.

Пример для nginx:

location / {
  try_files $uri /index.html;
}

Добавление и подключение стилей

CSS и CSS Modules

Вы можете использовать обычные .css-файлы, импортируя их в компоненты:

import './App.css'

Для изоляции классов используйте CSS Modules: файлы Component.module.css. Они обеспечивают скоупинг и защиту названий классов от коллизий.

import styles from './Button.module.css'
// Использование:
<button className={styles.primary}>Нажми меня</button>

Интеграция Sass и других препроцессоров

Для поддержки Sass установите соответствующий пакет:

npm install sass

Теперь можно использовать .scss файлы:

import './App.scss'

CRA и Vite поддерживают их из коробки.

Настройка прокси для API в dev-режиме

Чтобы обойти CORS-проблемы и упростить работу с внешними API на dev-сервере, настройте прокси в файле package.json (для CRA):

"proxy": "http://localhost:5000"

• Теперь запросы к /api/... автоматически будут перенаправляться на ваш backend-сервер.

Для Vite настройка прокси осуществляется в vite.config.js:

server: {
  proxy: {
    '/api': 'http://localhost:5000',
  }
}

Импорт и работа с изображениями

Чтобы добавить изображения, поместите их в папку src/assets/ (или другую внутри src/). Импортируйте их как модули:

import logo from './logo.png'

<img src={logo} alt="Logo" />

При сборке изображения автоматически добавляются в итоговый бандл, оптимизируются и получают уникальные имена.

Развертывание React-приложения на продакшн-сервере

Куда и как можно разместить приложение

React-приложение — это обычные статические файлы. Вы можете использовать:

• Хостинги статических сайтов: Netlify, Vercel, GitHub Pages
• Любой веб-сервер (nginx, Apache)
• S3/CloudFront и др.

Пример развертывания на Netlify

1. Зарегистрируйтесь на Netlify
2. Подключите репозиторий с вашим проектом.
3. В настройках задайте:
   • build command: npm run build
   • publish directory: build (или dist)

Netlify самостоятельно соберет проект и опубликует его.

Пример ручного развертывания на сервере с помощью nginx

1. Соберите проект:
   bash npm run build
2. Передайте содержимое папки build/ на сервер (через SCP, FTP, rsync и др.)
3. Настройте сервер так, чтобы отдавать файлы из build/, а любые несуществующие маршруты — на index.html.

Использование дополнительных инструментов (Eslint, Prettier, Husky)

Linting и форматирование

Для контроля качества кода разумно добавить линтеры и форматтеры. Вот пример установки:

npm install --save-dev eslint prettier

• Настройте .eslintrc и .prettierrc под свой стиль.
• Для автоматического запуска линтера при коммите добавьте Husky.

Проверка типизации с TypeScript

Если вы хотите использовать строгую типизацию, можно создать новый проект с поддержкой TS:

npx create-react-app my-ts-app --template typescript

• После этого скрипты сборки/запуска работают точно так же.

Заключение

Запуск и сборка React-приложения — это процесс, который состоит из нескольких последовательных шагов: инициализация проекта, запуск dev-сервера, настройка и создание production-сборки. Инструменты наподобие CRA или Vite существенно упрощают этот процесс, но при необходимости вы всегда можете перейти к ручной настройке сборщика для большего контроля. Не забывайте о правильной работе с переменными окружения, маршрутизацией и развертыванием на сервере. Правильная организация рабочих процессов (линтинг, форматирование, типизация) поможет поддерживать качество кода и легкость поддержки приложения.

Сборка и запуск приложения - важные этапы, но для полноценной разработки требуется умение управлять состоянием и навигацией. На курсе Основы React, React Router и Redux Toolkit вы получите все необходимые знания. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в основы React уже сегодня.

Частозадаваемые технические вопросы по теме и ответы на них

Почему после сборки приложения мои изображения не отображаются на сайте?

Обычно это связано с некорректным путем в src-атрибутах или тем, что картинки располагаются вне папки src или public. Убедитесь, что вы импортируете изображения с помощью import в компоненте (если они лежат в src), либо кладете их в public и ссылаетесь как /img/logo.png.

Как изменить порт, на котором запускается dev-сервер React?

Для Create React App можно указать порт с помощью переменной окружения. Например:

• В файле .env: PORT=4000
• При запуске из командной строки: PORT=4000 npm start

Как добавить поддержку абсолютных импортов в проекте CRA без eject?

Добавьте файл jsconfig.json в корень проекта и пропишите: json { "compilerOptions": { "baseUrl": "src" } } Теперь вы можете импортировать файлы относительно папки src, например: import Header from 'components/Header'.

После сборки у меня не работает маршрутизация через React Router. Почему?

Сервер должен перенаправлять все запросы (кроме статических файлов) на index.html. Для этого требуется соответствующая конфигурация сервера (например, для nginx используется try_files $uri /index.html;).

Что делать, если после сборки размер бандла очень большой?

• Проверьте импорт ли вы только необходимые компоненты и функции из библиотек.
• Используйте динамические импорты (React.lazy, Suspense).
• Оптимизируйте изображения и ассеты.
• Если используете свою сборку — подключите плагины минификации (Terser, CSSNano).
• Для CRA — проверьте, не подключены ли лишние библиотеки в package.json.