Hoe u privé Astro-componenten deelt zonder npm

Gedeeld beheer van componenten

Bij webontwikkeling komt het af en toe voor dat u dezelfde UI-componenten opnieuw wilt gebruiken op meerdere websites, toch?

Bij het ontwikkelen van meerdere sites met een modern framework zoals Astro is het delen van een componentenbibliotheek zeer effectief. Wanneer u componenten als npm-pakket deelt, is echter vaak een betaald abonnement nodig om privépakketten te publiceren.

In dit artikel laten we zien hoe u componenten efficiënt kunt delen en beheren zonder ze als npm-pakket te verpakken, met behulp van een GitHub-repository en Cloudflare Pages!

Wat zijn de uitdagingen bij het delen van componenten!?

Wilt u dezelfde UI-componenten gebruiken op meerdere Astro-sites!
Wilt u hosten op Cloudflare Pages!
Ik wil componenten beheren in een privé GitHub-repository!
Ik wil de componenten als npm-pakket publiceren, maar ik wil ze niet openbaar maken!

Zo ongeveer dan. Hoe zouden we dit het beste aanpakken?

Oplossen met een GitHub-repository en een aangepast buildscript

Om deze uitdagingen op te lossen, kunnen we het volgende aanpakken.

Een GitHub-repository voor de componenten aanmaken
Bestandsverwijzingen gebruiken voor lokale ontwikkeling
In de Cloudflare Pages-omgeving de componentrepository klonen tijdens de build

Zonder een privé npm-pakket kunnen componenten worden gedeeld en beheerd.

Zo ziet de implementatie eruit

1. GitHub-persoonlijk toegangstoken aanmaken

Maak een GitHub-persoonlijk toegangstoken aan om toegang te krijgen tot private repositories.

Log in op GitHub
Klik rechtsboven op het profielpictogram → Settings
Selecteer in de linkerzijbalk "Developer settings" → "Personal access tokens" → "Tokens (classic)"
Klik op "Generate new token" → "Generate new token (classic)"
Ken de volgende rechten toe aan het token:
- repo - volledige toegang tot private repositories
Genereer het token en bewaar het op een veilige plek (het wordt maar één keer getoond).

2. Een componentenbibliotheek bouwen

Maak een GitHub-repository voor de componenten aan (bijvoorbeeld: github.com/your-username/ui-components).

package.json van de componentenbibliotheek

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

3. Het hoofdproject instellen

Stel de package.json van het hoofdproject in dat de componenten gebruikt.

package.json van het hoofdproject

{
  "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などの開発依存関係
  }
}

De volgende vier punten zijn essentieel.

config-sectie: beheert de informatie over de componentenbibliotheek op één plek
setup-components-script: kloont de componenten tijdens het bouwen vanuit GitHub
build-with-components-script: een opdracht die het instellen van de componenten en het bouwen combineert
dependencies: bestandsverwijzingen voor lokale ontwikkeling

4. Lokale ontwikkelomgeving instellen

Kloon de componentenbibliotheek naast je project in dezelfde map en gebruik deze via bestandsverwijzingen.

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

Wijzigingen aan componenten tijdens lokale ontwikkeling worden direct doorgevoerd in het hoofdproject.

5. Cloudflare Pages instellen

Hieronder vind je de instellingen voor Cloudflare Pages.

Omgevingsvariabelen instellen:
- Pages-dashboard → your-project → Settings → Environment variables
- Variabelenaam: GITHUB_TOKEN
- Waarde: de GitHub Personal Access Token die je hebt aangemaakt
Buildcommando instellen:
- Pages-dashboard → your-project → Settings → Build & deployments
- Build command: npm run build-with-components
- Build output directory: dist (standaard)

Tijdens de build wordt de componentenbibliotheek in de opgegeven versie automatisch gekloond en opgenomen.

Componenten eenvoudig gebruiken na de configuratie

Zodra de configuratie is voltooid, is het gebruik van componenten heel eenvoudig.

Maak in de componentenbibliotheek een src/index.ts-bestand aan en exporteer de componenten.

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

Importeer de componenten die je wilt gebruiken in het hoofdproject.

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

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

Hoe zit het met versiebeheer?

Wanneer je een nieuwe versie van de componentenbibliotheek wilt uitbrengen,

Breng wijzigingen aan in de componentenbibliotheek en commit ze
Maak een nieuwe tag aan (bijv. v1.1.0)

Werk de package.json van het hoofdproject bij

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

Elk project kan de component gebruiken in de versie die het nodig heeft.

Ook de ontwikkelworkflow is veilig

Een veilige en efficiënte ontwikkelworkflow scheelt zorgen en werk, en dat is prettig.

Ontwikkel of wijzig nieuwe functies in de componentenbibliotheek (bijv. de branch feature/new-button)
Test en controleer die wijzigingen direct in het hoofdproject in de lokale omgeving
Zodra de ontwikkeling een bepaalde fase heeft bereikt, maak je een testtag aan (bijv. v1.1.0-test)
Werk componentVersion in de testomgevingbranch van het hoofdproject bij naar de testtag en deploy naar de testomgeving
Als de testomgeving geen problemen laat zien, voeg je de wijzigingen samen met de main-branch van de componentenbibliotheek
Het wordt live gezet door een nieuwe versietag aan te maken en de versie van het hoofdproject bij te werken (bijv. v1.1.0).

Het voordeel: je kunt wijzigingen aan componenten testen zonder invloed op de productieomgeving! Het voordeel: je kunt wijzigingen aan componenten testen zonder invloed op de productieomgeving!

De productieomgeving van Cloudflare Pages gebruikt de versie van de tag die is opgegeven in config.componentVersion. Zolang je geen nieuwe tag aanmaakt en config niet bijwerkt, heeft een wijziging dus geen invloed op productie, dus je kunt gerust zijn!

■ Geen npm-privépakketten nodig: combineer een GitHub-privérepository met een aangepast buildscript!

■ Met een zorgvuldig beheer van GitHub-tokens en een correcte lokale ontwikkelomgeving delen je hele team componenten naadloos!

Wat denk je ervan?

Is dit niet ideaal voor kleine tot middelgrote teams en projecten waarin kostenefficiëntie belangrijk is?

Mocht je team of project in de toekomst groeien, dan kun je later nog overstappen naar npm-privépakketten. Voorlopig denk ik dat deze aanpak ruimschoots voldoende is voor een efficiënte componentdeling!

Aanvullend: Deze aanpak werkt ook met andere frameworks dan Astro, zoals React, Vue en Svelte. De details van de configuratie kunnen verschillen, maar de basisaanpak blijft hetzelfde! Je kunt het buildproces op vergelijkbare wijze aanpassen bij andere hostingdiensten dan Cloudflare Pages.