Развернуть React на GitHub Pages

Плюшевая игрушка GitHub Octocat на фоне размытых терминальных строк .jpg?q=50&fit=crop&w=1100&h=618&dpr=1.5)

Зачем использовать GitHub Pages

GitHub Pages превращает репозитории в сайты и позволяет бесплатно хостить неограниченное количество проектных сайтов. Это удобно для демо, документации и простых SPA. Для React с навигацией требуется небольшая дополнительная конфигурация — эта инструкция покрывает весь процесс, от создания репозитория до доступного по URL сайта.

Создаём React-приложение (если нужно)

Если у вас уже есть проект — переходите к следующему разделу. Для демонстрации создадим новый проект с помощью create-react-app.

В терминале выполните:

npx create-react-app react-gh

Перейдите в созданную папку и запустите приложение:

npm run start

Откройте проект в редакторе. В папке src удалите всё, кроме App.js и index.js. Замените содержимое App.js на следующее:

function App() {  
  return (  
      
      Github Pages  
      Deploying React to Github  
      
  );  
}  
export default App;

Добавляем маршрутизацию

Установите react-router-dom:

npm install react-router-dom

В App.js добавьте ссылку на страницу About:

import { Link } from "react-router-dom";  
function App() {  
  return (  
      
      About  
      Github Pages  
      Deploying React to Github  
      
  );  
}  
export default App;

Создайте компонент About (файл About.js):

const About = () => {  
    return (   
          
          Home  
          About Page  
          
        );  
}  
export default About;

Теперь нужно настроить маршруты в index.js:

import React from "react";  
import ReactDOM from "react-dom";  
import App from "./App";  
import { HashRouter, Routes, Route } from "react-router-dom";  
import About from "./About";  
ReactDOM.render(  
    
      
        
        } />  
        }/>  
        
      
  ,  
  document.getElementById("root")  
);

Важно: мы используем HashRouter вместо BrowserRouter. На GitHub Pages в случае BrowserRouter часто возникает 404, потому что сервер не знает о маршрутах вашего SPA. HashRouter использует часть URL после # и не требует серверной настройки.

Закоммитьте изменения в Git:

git add .  
git commit -m "Create React app"

Создаём репозиторий на GitHub и пушим

Создайте новый репозиторий в своём аккаунте GitHub. Рекомендуется имя репозитория совпадать с локальной папкой.
Привяжите удалённый репозиторий:

git remote add origin /.git

Пушьте в main:

git branch -M main  
git push --set-upstream origin main

Развёртывание на GitHub Pages

Установите пакет gh-pages, который создаёт ветку gh-pages и публикует содержимое папки build:

npm install gh-pages

В package.json добавьте поле homepage и скрипты deploy (замените и ):

"homepage": "https://.github.io//",  
"scripts": {  
    "predeploy": "npm run build",  
    "deploy": "gh-pages -d build",   
    "start": "react-scripts start",  
    "build": "react-scripts build",  
    "test": "react-scripts test",  
    "eject": "react-scripts eject"  
  }

Запустите деплой:

npm run deploy

Через несколько секунд приложение будет доступно по адресу: https://.github.io/

Чеклист перед публикацией

Убедитесь, что в package.json правильный URL в поле homepage.
Проверьте, что приложение работает локально (npm run start).
Используйте HashRouter для навигации или настройте серверные редиректы при BrowserRouter.
Добавьте .nojekyll в корень, если используете нестандартные файлы (необязательно для CRA).
Убедитесь, что ветка main запушена и есть доступ к репозиторию.

Что делать, если что-то пошло не так (отладка)

Страница 404 после загрузки подмаршрута: проверьте, что вы используете HashRouter. Для BrowserRouter требуется настройка сервера, чего нет на GitHub Pages.
Сайт не обновляется после деплоя: очистите кэш браузера и проверьте, что gh-pages создала ветку gh-pages в репозитории.
Ошибки сборки: выполните npm run build локально и посмотрите логи — там обычно указана причина.
Проблемы с относительными путями к ресурсам: поле homepage задаёт базовый путь; убедитесь, что пути формируются относительно него.

Альтернативные подходы

Netlify или Vercel: поддерживают SPA и автоматические деплои из ветки, умеют настраивать редиректы и имеют встроенные функции CI/CD.
GitHub Actions: можно автоматизировать билд и деплой в gh-pages через workflow вместо локального npm run deploy.
Настройка собственного домена: GitHub Pages поддерживает кастомные домены. Добавьте CNAME и настройте DNS у регистратора.

Модель принятия решения (когда использовать GitHub Pages)

Подходит, если вам нужен простой бесплатный хостинг для статического SPA, документации или демо.
Не подходит для серверной логики, динамических API или приложений с приватными данными — для этого нужен бекенд.

Краткая методология (SOP) для быстрой публикации

Проверка локальной работоспособности (npm run start).
Обновление package.json (homepage + scripts).
Установка gh-pages (npm install gh-pages).
git add, commit, push в main.
npm run deploy и проверка URL.

Короткий глоссарий

HashRouter — роутер, использующий часть URL после #; полезен для статических хостов.
gh-pages — npm-пакет для публикации содержимого build в ветку gh-pages.
homepage — поле package.json, задаёт базовый путь приложения на GitHub Pages.

Безопасность и данные

GitHub Pages служит только статическим файлам. Не храните в репозитории секреты (API-ключи, пароли). Для приватных данных используйте серверную часть или защищённые хранилища.

Итог

Развёртывание React‑приложения на GitHub Pages — быстрый и бесплатный способ опубликовать SPA. Главное — правильно настроить маршрутизацию (рекомендуется HashRouter) и указать homepage в package.json. Варианты с Netlify/Vercel и GitHub Actions дают больше гибкости для CI/CD и кастомных редиректов.

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

Критерии приёмки