Застосавайце прыграмы Vite TypeScript на GitHub Pages без зберагання файла dist

Непаўзліва інтэграцыя для фронтэнда на Vite + TypeScript часта выконваліцца на GitHub Pages. Частая памылка — запісваць створаную структуру dist у стандартны гілку. Наведзены выкладком працэс не дазволяе артыфактам парадувацца ў git: Actions стварае продукты пасля кожнага аплыву, тымчасова заваносіць вынік і публікуе яго праз 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

Створыце заданне 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

Разумеўце заданне

У пайплайне ёсць чатыры элемента:

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 ў меру росту праекта.

Лепшае рашынак — гучна паведамленне пра адзіёўку пад час выканання npm run build з спамою, чым публікацыя непаштоўнага dist. Закрэпіце версію Node ў працэсе працы так, каб яна падтрымвалася ў локальнай асяроддзі разработкі, тады функцыі на кшталт optional-chaining чы новейшыя можлівасці TypeScript не будуць працаваць на ноутбуку, але будуць працаваць на серверэ. Калі сайт выкарыстоўвае адзінаковы домэн, памятайце, што Pages все рава выклікае тыя ж трэбаванні да base і basename рутэра, як і для URL у фармаце project-pages пад username.github.io/repo. Публічны прыклад рэпазітарыя пад назвай barreiradlc/github-pages-deploy паказвае той самы шаблон, і GitHub Pages можа размясціць створаную дэманстрацыю з гэтага праекту.