Розгорніть додатки Vite TypeScript на GitHub Pages без збереження файлу dist

Неперервна інтеграція фронтенду на Vite + TypeScript зазвичай спрямована на GitHub Pages. Поширеною помилкою є збереження створеної структури dist у стандартній гілці. Наведена нижче схема роботи не дозволяє вносити ці артефакти до git: Actions компілює код після кожного pushу, тимчасово завантажує результати та публікує їх через API розгортання Pages.

Чому варто уникати відстеження папки dist?

Результати компіляції мають знаходитися поза системою контролю версій з кількох причин:

1. Надмірний об’єм репозиторію: Бандли є великими та численними; додатки для мобільних пристроїв або з великою кількістю ресурсів можуть швидко досягати меж об’єму.
2. Конфлікти при злитті: Перегенеровані файли можуть конфліктувати між гілками навіть у разі, коли зміни в кодовому джерелі не пов’язані.
3. Плутанина: Оглядачі втрачають розуміння меж між редаговуваним кодом та нерозбірливими продуктами компіляції.

Практика CI/CD: Артефакти мають бути тимчасовими та створюватися за потребою.

Налаштування проекту

Створіть додаток на TypeScript з React за допомогою Vite:

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

Очікуйте лейаут, схожий на цей:

my-app/
├── src/
│ ├── App.tsx
│ ├── main.tsx
│ └── …
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── .gitignore

Налаштування Vite для GitHub Pages

GitHub Pages розміщує сайти проектів під підрозділом репозиторію, тому Vite потребує явного значення base. Оновіть vite.config.ts:

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

export default defineConfig({
 plugins: [react()],
 base: '/your-repo-name/', // Replace with your repository name, in my case: "github-pages-deploy"
})

Додайте базову URL до вашого маршрутизатора (якщо використовується React Router)

Клієнтські маршрутизатори повинні використовувати цей підрозділ через basename:

import { BrowserRouter } from 'react-router-dom'

function App() {
  return (
    <BrowserRouter basename="/your-repo-name/">
      {/* Your routes */}
    </BrowserRouter>
  )
}

Оновлення .gitignore

Залиште результати компіляції поза увагою:

# .gitignore
node_modules
dist
dist-ssr
*.local

Створення workflow у GitHub Actions

Додайте файл .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: ['main']  # or 'master'
  workflow_dispatch:    # Allow manual trigger

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Розуміння workflow

Цей пайплайн складається з чотирьох етапів:

1. Тригер: запускається при збільшенні кількості комітів у main (може дозволяти ручний запуск).
2. Завдання зі складання: встановлює залежності та створює файл dist.
3. Завантаження артефакта: зберігає dist як артефакт Actions — ніколи не як коміт у git.
4. Завдання з розгортання: публікує цей артефакт через GitHub Pages.

Коротко кажучи: репозиторій залишається лише джерелом коду, Actions тимчасово зберігає результати складання, а Pages обслуговує завантажені файли.

Налаштування GitHub Pages

1. Відкрийте репозиторій на GitHub.
2. Перейдіть до Settings → Pages.
3. У розділі „Build and deployment“ виберіть GitHub Actions як джерело, щоб Pages більше не очікував публікації з гілки чи папки docs.

Перевірка розгортання

Спробуйте повний процес:

1. Опублікуйте зміни у main:

git add .
git commit -m "Initial setup with GitHub Actions deployment"
git push origin main

1. Слідкуйте за процесом виконання у вкладці Actions.
2. Після успішного виконання відкрийте https://your-username.github.io/your-repo-name/.

Висновок

Отриманий конвеєр обробки:

• Автоматично створює додаток на Vite + TypeScript
• Опублікує його на GitHub Pages без збереження папки dist
• Зберігає репозиторій лише з вихідним кодом
• Поновлює розгортання після кожної відповідної опублікації

Розділення вихідного коду та готових результатів полегшує співпрацю та зменшує несподіванки під час розгортання. Перевіряйте результати після значних змін у робочому процесі чи маршрутизації, а також підтримуйте сумісність YAML у міру зростання проекту.

Краще голосно повідомити про невдачу під час виконання завдання Actions у разі помилок npm run build, ніж публікувати неповний файл dist. Встановіть конкретну версію Node у процесі роботи, щоб вона збігалася з версією на локальному розробницькому середовищі, адже функції типу optional-chaining чи новіші можливості TypeScript можуть працювати на ноутбуці, але не спрацьовувати на сервері. Якщо сайт використовує власний домен, пам’ятайте, що Pages все одно потребує такої ж структури base та параметра basename для маршрутизатора, як і у проекті типу pages під адресою username.github.io/repo. Публічний приклад репозиторію під назвою barreiradlc/github-pages-deploy демонструє таку саму структуру, і GitHub Pages може розміщувати готову демонстрацію з цього проекту.