Wie man private Astro-Komponenten ohne npm teilt

Verwaltung gemeinsam genutzter Komponenten

In der Webentwicklung kommt es selten vor, dass man dieselben UI-Komponenten auf mehreren Websites wiederverwenden möchte, oder?

Wenn Sie mit einem modernen Framework wie Astro die Entwicklung mehrerer Websites effizienter gestalten möchten, ist die gemeinsame Nutzung einer Komponentenbibliothek sehr hilfreich. Werden die Komponenten jedoch als npm-Paket geteilt, ist dafür häufig ein kostenpflichtiger Tarif für die Veröffentlichung privater Pakete erforderlich.

In diesem Beitrag zeigen wir, wie Sie Komponenten ohne npm-Paketierung effizient teilen und verwalten können, indem Sie ein GitHub-Repository und Cloudflare Pages nutzen.

Die Herausforderung beim Teilen von Komponenten!?

Dieselben UI-Komponenten in mehreren Astro-Websites verwenden!
Auf Cloudflare Pages hosten!
Komponenten in einem privaten GitHub-Repository verwalten!
Komponenten als npm-Paket bereitstellen, aber nicht öffentlich zugänglich machen!

So in etwa. Wie könnte man das am besten umsetzen?

Lösung mit einem GitHub-Repository und einem benutzerdefinierten Build-Skript

Um diese Herausforderungen zu lösen, schlagen wir folgenden Ansatz vor.

GitHub-Repository für die Komponenten anlegen
In der lokalen Entwicklung Dateiverweise verwenden
In der Cloudflare-Pages-Umgebung das Komponenten-Repository beim Build klonen

Komponenten lassen sich so ohne privates npm-Paket teilen und verwalten.

So sieht die Umsetzung aus

1. GitHub Personal Access Token erstellen

Erstellen Sie einen GitHub Personal Access Token, um auf private Repositories zuzugreifen.

Bei GitHub anmelden
Klicken Sie oben rechts auf das Profilsymbol → Settings
Wählen Sie in der linken Seitenleiste „Developer settings“ → „Personal access tokens“ → „Tokens (classic)“
Klicken Sie auf „Generate new token“ → „Generate new token (classic)“
Weisen Sie dem Token folgende Berechtigung zu:
- repo – Vollzugriff auf private Repositories
Generieren Sie das Token und speichern Sie es an einem sicheren Ort (es wird nur einmal angezeigt).

2. Aufbau der Komponentenbibliothek

Erstellen Sie ein GitHub-Repository für die 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 einrichten

Richten Sie die package.json des Hauptprojekts ein, 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://[email protected]/$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などの開発依存関係
  }
}

Auf die folgenden vier Punkte kommt es an.

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

4. Lokale Entwicklungsumgebung einrichten

Klonen Sie die Komponentenbibliothek auf derselben Ebene wie Ihr Projekt und verwenden Sie sie über Dateiverweise.

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

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

5. Konfiguration von Cloudflare Pages

Die Einstellungen für Cloudflare Pages finden Sie hier.

Einrichtung der Umgebungsvariablen:
- Pages-Dashboard → your-project → Settings → Environment variables
- Variablenname: GITHUB_TOKEN
- Wert: Ihr erstellter GitHub Personal Access Token
Konfiguration des Build-Befehls:
- Pages-Dashboard → your-project → Settings → Build & deployments
- Build command: npm run build-with-components
- Build-Ausgabeverzeichnis: dist (Standard)

Beim Build wird die Komponentenbibliothek in der angegebenen Version automatisch geklont und eingebunden.

Komponenten nach der Einrichtung unkompliziert nutzen

Nach Abschluss der Einrichtung ist die Verwendung der Komponenten ganz einfach.

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

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

Importieren Sie im Hauptprojekt die gewünschten Komponenten.

---
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,

Änderungen an der Komponentenbibliothek vornehmen und committen
Neuen Tag erstellen (z. B. v1.1.0)

package.json des Hauptprojekts aktualisieren

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

Jedes Projekt kann die Komponenten in der jeweils benötigten Version verwenden.

Auch der Entwicklungsablauf ist sicher

Ein sicherer und effizienter Entwicklungsablauf spart Aufwand bei Dingen, auf die Sie achten müssten.

Neue Funktionen entwickeln und Änderungen in der Komponentenbibliothek vornehmen (z. B. im Branch feature/new-button)
Diese Änderungen lassen sich in der lokalen Umgebung sofort im Hauptprojekt testen und überprüfen.
Sobald die Entwicklung einen bestimmten Stand erreicht hat, einen Test-Tag erstellen (z. B. v1.1.0-test)
Im Branch für die Testumgebung des Hauptprojekts componentVersion auf den Test-Tag aktualisieren und in der Testumgebung bereitstellen
Wenn die Testumgebung keine Probleme zeigt, den Branch in den main-Branch der Komponentenbibliothek mergen
Die Veröffentlichung erfolgt durch das Erstellen eines neuen Versions-Tags und die Aktualisierung der Version im Hauptprojekt (z. B. v1.1.0).

Das Besondere: Komponentenänderungen lassen sich testen, ohne die Produktivumgebung zu beeinflussen!

Die Produktionsumgebung von Cloudflare Pages verwendet die Version des Tags, die in config.componentVersion angegeben ist. Solange Sie keinen neuen Tag erstellen und config nicht aktualisieren, haben Änderungen daher keinen Einfluss auf die Produktivumgebung. Das gibt Sicherheit!

■ Ohne private npm-Pakete: Kombination aus einem privaten GitHub-Repository und einem eigenen Build-Skript!

■ Durch sorgfältige Verwaltung des GitHub Tokens und eine korrekte lokale Entwicklungsumgebung gelingt die nahtlose Freigabe von Komponenten im gesamten Team!

Was meinen Sie?

Ist dieser Ansatz nicht ideal für kleine bis mittelgroße Teams und Projekte, bei denen die Kosteneffizienz im Vordergrund steht?

Sollten Teams oder Projekte in Zukunft wachsen, lässt sich ein Wechsel zu privaten npm-Paketen immer noch prüfen. Vorerst dürfte diese Methode jedoch eine effiziente Komponentenfreigabe ermöglichen!

Hinweis: Der Ansatz funktioniert auch mit anderen Frameworks als Astro, etwa React, Vue oder Svelte. Die Konfigurationsdetails können abweichen, das grundlegende Vorgehen bleibt jedoch gleich! Auch bei anderen Hosting-Diensten lässt sich der Build-Prozess auf ähnliche Weise anpassen.