So teilen Sie private Astro-Komponenten ohne npm

Komponentenfreigabe und -verwaltung

Bei der Web-Entwicklung kommt es vor, dass Sie dieselben UI-Komponenten auf mehreren Websites wiederverwenden möchten.

Wenn Sie moderne Frameworks wie Astro verwenden, um die Entwicklung mehrerer Websites zu optimieren, ist die gemeinsame Nutzung von Komponentenbibliotheken äußerst effektiv. Wenn Sie Komponenten jedoch als npm-Paket freigeben möchten, benötigen Sie einen kostenpflichtigen Plan für private Pakete.

Dieses Mal zeigen wir Ihnen, wie Sie Komponenten effizient mit einem GitHub-Repository und Cloudflare Pages freigeben und verwalten, ohne sie mit npm zu packen!

Welche Herausforderungen gibt es bei der Komponentenfreigabe?

Ich möchte dieselben UI-Komponenten auf mehreren Astro-Websites verwenden!
Ich möchte auf Cloudflare Pages hosten!
Komponenten in einem privaten GitHub-Repository verwalten!
Komponenten als npm-Paket erstellen, aber nicht veröffentlichen!

Genau. Wie lässt sich das am besten lösen?

GitHub-Repository und benutzerdefiniertes Build-Skript als Lösung

Um diese Herausforderungen zu bewältigen, empfehlen wir folgenden Ansatz:

Ein GitHub-Repository für Komponenten erstellen
In der lokalen Entwicklung Dateireferenzen verwenden
In der Cloudflare Pages-Umgebung das Komponenten-Repository beim Build klonen

Komponenten können ohne private npm-Pakete freigegeben und verwaltet werden.

Die Implementierung sieht folgendermaßen aus:

1. Erstellen Sie ein GitHub Personal Access Token

Erstellen Sie ein GitHub Personal Access Token für den Zugriff auf private Repositories.

Bei GitHub anmelden
Klicken Sie auf das Profilsymbol oben rechts → Einstellungen
Wählen Sie in der linken Seitenleiste „Developer settings" → „Personal access tokens" → „Tokens (classic)"
Klicken Sie auf „Generate new token" → „Generate new token (classic)"
Dem Token werden folgende Berechtigungen erteilt:
- repo - Vollständiger Zugriff auf private Repositorys
Token generieren und an einem sicheren Ort speichern (wird nur einmal angezeigt)

2. Erstellung einer Komponentenbibliothek

Erstellen Sie ein GitHub-Repository für Komponenten (Beispiel: github.com/your-username/ui-components).

package.json der Komponentenbibliothek

{
  "name": "@your-org/components",
  "private": true,
  "type": "module",
  "main": "src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "files": [
    "src"
  ],
  "peerDependencies": {
    "astro": "^5.7.12"
  }
}

3. Hauptprojekt konfigurieren

Konfigurieren Sie die package.json des Hauptprojekts, das die Komponenten verwendet.

package.json des Hauptprojekts

{
  "name": "your-astro-project",
  "type": "module",
  "private": true,
  "config": {
    "componentVersion": "v1.0.0",
    "orgName": "your-username",
    "repoName": "ui-components",
    "namespace": "your-org",
    "packageName": "components"
  },
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "setup-components": "set -e; ORG_NAME=\\\\"$npm_package_config_orgName\\\\"; REPO_NAME=\\\\"$npm_package_config_repoName\\\\"; NAMESPACE=\\\\"$npm_package_config_namespace\\\\"; PACKAGE_NAME=\\\\"$npm_package_config_packageName\\\\"; VERSION=\\\\"$npm_package_config_componentVersion\\\\"; mkdir -p temp; git clone -b $VERSION <https://$GITHUB_TOKEN@github.com/$ORG_NAME/$REPO_NAME.git> temp/$REPO_NAME; mkdir -p node_modules/@$NAMESPACE; ln -sf $(pwd)/temp/$REPO_NAME node_modules/@$NAMESPACE/$PACKAGE_NAME",
    "build-with-components": "npm run setup-components && npm run build"
  },
  "dependencies": {
    "@your-org/components": "file:../ui-components"
  },
  "devDependencies": {
    // Astroなどの開発依存関係
  }
}

Die folgenden 4 Punkte sind entscheidend.

config-Abschnitt: Zentralisierte Verwaltung der Informationen zur Komponentenbibliothek
setup-components-Skript: Komponenten während des Builds von GitHub klonen
build-with-components-Skript: Kombinierter Befehl für Komponenten-Setup und Build
dependencies: Dateireferenzen für die lokale Entwicklung

4. Lokale Entwicklungsumgebung einrichten

Klonen Sie die Komponentenbibliothek in dieselbe Verzeichnisebene wie Ihr Projekt und verwenden Sie Dateireferenzen.

projects/
  ├── ui-components/         # コンポーネントライブラリ
  └── your-astro-project/     # メインプロジェクト

Änderungen an Komponenten während der lokalen Entwicklung werden sofort im Hauptprojekt widergespiegelt.

5. Cloudflare Pages-Konfiguration

Hier ist die Konfiguration für Cloudflare Pages.

Umgebungsvariablen einrichten:
- Pages-Dashboard → your-project → Settings → Environment variables
- Variablenname: GITHUB_TOKEN
- Wert: Ihr erstelltes GitHub Personal Access Token
Build-Befehl konfigurieren:
- Pages-Dashboard → your-project → Settings → Build & deployments
- Build command: npm run build-with-components
- Build-Ausgabeverzeichnis: dist (Standard)

Beim Build wird die angegebene Version der Komponentenbibliothek automatisch geklont und integriert.

Nach der Konfiguration sind Komponenten einfach einsatzbereit

Nach Abschluss der Konfiguration ist die Verwendung von Komponenten sehr einfach.

Erstellen Sie src/index.ts in der Komponentenbibliothek und exportieren Sie die Komponenten.

export { default as Button } from './components/base/Button.astro';
export { default as Heading } from './components/base/Heading.astro';
// 他のコンポーネントもここでエクスポート

Importieren Sie die Komponenten, die Sie im Hauptprojekt verwenden möchten.

---
import { Button, Heading } from '@your-org/components';
---

<div>
  <Heading>Hello World</Heading>
  <Button>Click me</Button>
</div>

Wie funktioniert die Versionsverwaltung?

Wenn Sie eine neue Version der Komponentenbibliothek veröffentlichen möchten,

nehmen Sie Änderungen an der Komponentenbibliothek vor und committen Sie diese
Neues Tag erstellen (z. B. v1.1.0)

package.json des Hauptprojekts aktualisieren

"config": {
  "componentVersion": "v1.1.0",
  // 他の設定...
}

Jedes Projekt kann die erforderliche Version der Komponenten verwenden.

Der Entwicklungsablauf ist ebenfalls sicher

Ein sicherer und effizienter Entwicklungsablauf bedeutet weniger Sorgen und mehr Zufriedenheit.

Entwicklung und Überarbeitung neuer Funktionen in der Komponentenbibliothek durchführen (z. B. Branch feature/new-button)
Änderungen können in der lokalen Umgebung sofort im Hauptprojekt getestet und überprüft werden
Wenn die Entwicklung einen bestimmten Stand erreicht hat, ein Test-Tag erstellen (z. B. v1.1.0-test)
componentVersion im Test-Branch des Hauptprojekts auf das Test-Tag aktualisieren und in der Test-Umgebung bereitstellen
Nach Bestätigung, dass in der Test-Umgebung alles in Ordnung ist, in den Main-Branch der Komponentenbibliothek mergen
Ein neues Versionstag wird erstellt und die Version des Hauptprojekts wird aktualisiert, wodurch die Änderungen in die Produktion übernommen werden (Beispiel: v1.1.0)

Der Vorteil liegt darin, dass Sie Komponentenänderungen testen können, ohne die Produktionsumgebung zu beeinflussen!

Die Produktionsumgebung von Cloudflare Pages verwendet die Version des in config.componentVersion angegebenen Tags. Solange Sie kein neues Tag erstellen und config nicht aktualisieren, wirken sich Ihre Änderungen nicht auf die Produktionsumgebung aus – sehr beruhigend!

■ Kombinieren Sie ein privates GitHub-Repository und benutzerdefinierte Build-Skripte, anstatt npm-Pakete mit privatem Zugriff zu verwenden!

■ Durch die ordnungsgemäße Verwaltung von GitHub-Token und die korrekte Konfiguration der lokalen Entwicklungsumgebung können Sie Komponenten nahtlos im gesamten Team austauschen!

Was halten Sie davon?

Diese Methode eignet sich besonders für kleine bis mittlere Teams oder Projekte, bei denen Kosteneffizienz im Fokus steht.

Falls Ihr Team oder Projekt in Zukunft wächst, können Sie jederzeit zu npm-Paketen mit privatem Zugriff wechseln. Für jetzt sollte diese Methode jedoch ausreichend effizient für die gemeinsame Komponentenverwaltung sein!

Anmerkung: Dieser Ansatz lässt sich auch auf andere Frameworks als Astro anwenden (React, Vue, Svelte usw.). Die Konfigurationsdetails können unterschiedlich sein, aber das grundlegende Vorgehen ist dasselbe! Auch bei anderen Hosting-Services als Cloudflare Pages können Sie den Build-Prozess auf ähnliche Weise anpassen.