Wdroż aplikacje Vite TypeScript na GitHub Pages bez zapisywania pliku dist

Ciągła integracja frontendu opartego na Vite + TypeScript zazwyczaj jest skierowana na GitHub Pages. Powszechnym błędem jest komitowanie utworzonego drzewa dist do gałęzi domyślnej. Poniższy proces pracy zapobiega umieszczaniu tych plików w git: Actions buduje aplikację przy każdym pushu, tymczasowo przesyła wyniki i publikuje je za pośrednictwem API deployment Pages.

Dlaczego unikać śledzenia foldera dist?

Wyniki generowane powinny znajdować się poza kontrolą wersji z kilku powodów:

1. Zadzieranie repozytorium: Pliki związane z budową są duże i liczne; aplikacje mobilne lub te z dużą ilością zasobów mogą szybko osiągnąć limity rozmiaru.
2. Konflikty przy łączeniu gałęzi: Ponownie utworzone pliki mogą kolidować pomiędzy różnymi gałęziami, nawet jeśli zmiany w źródle nie są ze sobą powiązane.
3. Zamieszanie: Osoby przeglądające kod tracą poczucie granicy pomiędzy edytowalnym źródłem a nieprzejrzystymi produktami budowania.

Zasady CI/CD: Artefakty powinny być tymczasowe i wytwarzane na żądanie.

Ustawienie projektu

Stwórz aplikację TypeScript React za pomocą Vite:

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

Oczekuj układu podobnego do tego:

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

Konfiguracja Vite dla GitHub Pages

GitHub Pages serwuje strony projektów pod podpathem repozytorium, dlatego Vite wymaga wyraźnej wartości base. Zaktualizuj plik 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"
})

Dodanie adresu bazowego do routera (jeśli używasz React Router)

Routery po stronie klienta muszą używać tego samego podpathu poprzez basename:

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

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

Zaktualizowanie pliku .gitignore

Nie ignoruj wyników budowania:

# .gitignore
node_modules
dist
dist-ssr
*.local

Stworzenie workflow w GitHub Actions

Dodaj plik .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

Rozumienie workflow

Pipeline składa się z czterech etapów:

1. Wyzwalacz: uruchamia się przy dodawaniu zmian do main (może również umożliwiać ręczne uruchomienie).
2. Zadanie budowania: instaluje zależności i tworzy pliki z katalogu dist.
3. Zapis artefaktu: przechowuje pliki z dist jako artefakt Actions — nigdy jako komit w git.
4. Zadanie deploju: publikuje ten artefakt za pośrednictwem GitHub Pages.

Krótko mówiąc: repozytorium pozostaje wyłącznie źródłem kodu, Actions tymczasowo przechowuje wyniki budowania, a Pages serwuje załadowane pliki.

Konfiguracja GitHub Pages

1. Otwórz repozytorium na GitHubie.
2. Wejdź w Ustawienia → Pages.
3. W sekcji „Budowanie i deploj” wybierz GitHub Actions jako źródło, aby Pages przestał oczekiwać publikacji z gałęzi lub folderu docs.

Próba deploju

Wykonaj pełną ścieżkę:

1. Wypchnij zmiany do main:

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

1. Obserwuj przebieg w zakładce Actions.
2. Po pomyślnym zakończeniu otwórz https://twoje-imię-username.github.io/nazwa-twojego-repozytorium/.

Wniosek

Otrzymany pipeline:

• Automatycznie buduje aplikację Vite + TypeScript
• Publikuje ją na GitHub Pages bez zapisywania plików z katalogu dist
• Zachowuje repositoryum wyłącznie z plikami źródłowymi
• Ponownie ją wdraża przy każdym odpowiednim wypchnięciu zmian

Rozdzielenie plików źródłowych od artefaktów ułatwia współpracę i zmniejsza niespodzianki podczas wdrażania. Ponownie przetestuj aplikację po dużych zmianach w procesie pracy lub routingu, a także utrzymuj spójność plików YAML w miarę rozwoju projektu.

Lepiej głośno przyznać się do niepowodzenia w zadaniu Actions przy błędach w npm run build, zamiast publikować niekompletne pliki z katalogu dist. Ustal w procesie pracy konkretną wersję Node, aby była zgodna z tą używaną podczas rozwoju lokalnego – w ten sposób opcje typu optional-chaining oraz nowsze funkcje TypeScript będą działać poprawnie na laptopie i nie zawiodą na serwerze. Jeśli strona korzysta z domeny własnej, pamiętaj, że Pages nadal wymaga takiej samej struktury base oraz basename routera jak w przypadku adresu typu project-pages pod adresem username.github.io/repo. Publiczny repozytorium przykładowe o nazwie barreiradlc/github-pages-deploy pokazuje ten sam schemat, a GitHub Pages może hostować stworzoną tam demonstrację.