Stellen Sie Vite-TypeScript-Anwendungen auf GitHub Pages bereit, ohne den dist-Ordner zu commiten.

Die kontinuierliche Integration für eine Vite + TypeScript-Frontend-Lösung zielt in der Regel auf GitHub Pages ab. Ein häufiger Fehler besteht darin, den gebauten dist-Ordner in die Standardbranche zu kommittieren. Der unten beschriebene Workflow hält die Artefakte außerhalb von Git: Actions baut bei jedem Push, lädt das Ergebnis vorübergehend hoch und veröffentlicht es über die Pages-Deployment-API.

Warum sollte man den dist-Ordner nicht verfolgen?

Die generierten Ausgaben gehören aus mehreren Gründen nicht in die Versionskontrolle:

1. Repositoriums-Überlastung: Die Bundles sind groß und zahlreich; mobile oder ressourcenintensive Anwendungen können schnell die Größenbegrenzungen erreichen.
2. Fusionskonflikte:Auch wenn die Quellcode-Änderungen unverwandt sind, kommen bei erneut generierten Dateien zwischen den Branchen Konflikte zustande.
3. Konfusion:Prüfer verlieren die Unterscheidung zwischen editierbarem Quellcode und unklaren Build-Produkten.

CI/CD-Praxis: Artefakte sollten vorübergehend sein und auf Anfrage erzeugt werden.

Projekteinrichtung

Erstellen Sie eine TypeScript-React-Anwendung mit Vite:

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

Es erwartet sich ein Layout, das dem folgenden ähnelt:

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

Vite für GitHub Pages konfigurieren

GitHub Pages stellt Projektseiten unter einem Unterpfad des Repositoriums bereit, daher benötigt Vite einen expliziten base. Aktualisieren Sie 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"
})

Base-URL zum Router hinzufügen (falls React Router verwendet wird)

Klientside-Routern müssen diesen Unterpfad über basename teilen:

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

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

.gitignore aktualisieren

Lassen Sie die Build-Ausgabe weiterhin ignoriert werden:

# .gitignore
node_modules
dist
dist-ssr
*.local

GitHub Actions Workflow erstellen

Fügen Sie .github/workflows/deploy.yml hinzu:

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

Verständnis des Workflows

Der Pipeline umfasst vier Schritte:

1. Trigger: wird bei Pushes in die main-Branch ausgeführt (und ermöglicht auch eine manuelle Auslösung).
2. Build-Job: installiert Abhängigkeiten und erzeugt die dist-Dateien.
3. Artikel hochladen: speichert die dist-Dateien als Actions-Artikel – niemals als Git-Commit.
4. Deploy-Job: veröffentlicht diesen Artikel über GitHub Pages.

Kurz gesagt: Das Repository bleibt ausschließlich als Quellcode erhalten, Actions speichert die gebauten Dateien vorübergehend, und Pages stellt die hochgeladenen Dateien zur Verfügung.

GitHub Pages konfigurieren

1. Öffnen Sie das Repository auf GitHub.
2. Gehen Sie zu Einstellungen → Pages.
3. Unter „Build and deployment“ wählen Sie GitHub Actions als Quelle, damit Pages keine Veröffentlichung aus einer Branch oder dem docs-Ordner mehr erwartet.

Ihre Bereitstellung testen

Führen Sie den gesamten Ablauf durch:

1. Pushen in main:

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

1. Beobachten Sie den Ablauf unter der Karteikarte Actions.
2. Sobald es erfolgreich war, öffnen Sie https://your-username.github.io/your-repo-name/.

Fazit

Die resultierende Pipeline:

• baut die Vite + TypeScript-Anwendung automatisch auf
• veröffentlicht sie auf GitHub Pages, ohne dist zu speichern
• behält das Repository auf Quellcode beschränkt
• führt bei jedem geeigneten Push erneut eine Bereitstellung durch

Durch Trennung von Quellcode und Ergebnissen wird die Zusammenarbeit erleichtert und unerwartete Probleme bei der Bereitstellung verringert. Testen Sie erneut nach großen Änderungen am Workflow oder an der Routing-Struktur und halten Sie das YAML im Laufe des Projektwachstums aktuell.

Es ist besser, laut Fehlermeldungen bei der Ausführung von „Actions“ zu erhalten, wenn npm run build fehlschlägt, anstatt eine unvollständige dist-Datei zu veröffentlichen. Legen Sie in dem Workflow die Node-Version fest, damit sie mit der lokalen Entwicklung übereinstimmt – so funktionieren Optionals-Chaining sowie neuere TypeScript-Funktionen auf dem Laptop und nicht auf dem Ausführungsserver. Wenn die Website eine eigene Domain verwendet, denken Sie daran, dass GitHub Pages weiterhin dieselbe Struktur für base und basename des Routers benötigt wie bei einer Projekt-URL unter username.github.io/repo. Ein öffentliches Beispiel-Repository mit dem Namen barreiradlc/github-pages-deploy zeigt dieses Muster, und GitHub Pages kann die daraus erstellte Demo beherbergen.