Hoe u private Astro-componenten zonder npm kunt delen

Beheer van het delen van componenten

Bij webontwikkeling wilt u regelmatig dezelfde UI-componenten op meerdere websites hergebruiken, toch?

Wanneer u moderne frameworks zoals Astro gebruikt om de ontwikkeling van meerdere sites efficiënter te maken, is het delen van componentenbibliotheken erg effectief. Echter, als u componenten als npm-pakketten wilt delen, vereist het publiceren van private pakketten een betaald abonnement.

Dit keer presenteren we u een manier om componenten efficiënt te delen en te beheren met behulp van een GitHub-repository en Cloudflare Pages, zonder pakketten in npm!

Wat zijn de uitdagingen bij het delen van componenten?

Ik wil dezelfde UI-componenten gebruiken op meerdere Astro-sites!
Ik wil deze hosten op Cloudflare Pages!
Ik wil componentenbeheer doen via een privé-repository op GitHub!
Ik wil componenten als npm-pakket maken, maar ze niet openbaar maken!

Ja, dat klopt. Hoe pakken we dit aan?

GitHub-repository en aangepast buildscript als oplossing

Om deze problemen op te lossen, zou dit een goede aanpak zijn.

Maak een GitHub-repository voor de componenten
Gebruik bestandsverwijzingen voor lokale ontwikkeling
Clone de componentenrepository tijdens het bouwen in Cloudflare Pages-omgeving

Componenten kunnen nu zonder npm-privépakket worden gedeeld en beheerd.

Zo ziet de implementatie eruit

1. GitHub Personal Access Token aanmaken

Maak een GitHub Personal Access Token aan om toegang te krijgen tot privérepository's.

Log in op GitHub
Klik op het profielicoon in de rechterbovenhoek → Instellingen
Selecteer in de linkerzijbalk "Developer settings" → "Personal access tokens" → "Tokens (classic)"
Klik op "Generate new token" → "Generate new token (classic)"
Verleen de volgende machtigingen aan het token:
- repo - volledige toegang tot privérepository's
Genereer het token en bewaar het op een veilige locatie (het wordt slechts eenmaal weergegeven)

2. Componentbibliotheek bouwen

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

package.json van de componentbibliotheek

{
  "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

Configureer de package.json van het hoofdproject 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://$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などの開発依存関係
  }
}

Deze vier punten zijn cruciaal.

config-sectie: centraal beheer van informatie over de componentbibliotheek
setup-components-script: kloon componenten van GitHub tijdens het bouwen
build-with-components-script: commando dat componentsetup en build combineert
dependencies: bestandsverwijzingen voor lokale ontwikkeling

4. Configureer uw lokale ontwikkelingomgeving

Kloon de componentbibliotheek in dezelfde mapstructuur als uw project en gebruik bestandsverwijzingen.

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

Wanneer u componenten lokaal wijzigt tijdens de ontwikkeling, worden de wijzigingen onmiddellijk in uw hoofdproject weergegeven.

5. Cloudflare Pages configureren

Hier vindt u de configuratie-instructies voor Cloudflare Pages.

Omgevingsvariabelen instellen:
- Pages-dashboard → your-project → Settings → Environment variables
- Variabelnaam: GITHUB_TOKEN
- Waarde: uw GitHub Personal Access Token
Bouwcommando configureren:
- Pages-dashboard → your-project → Settings → Build & deployments
- Build command: npm run build-with-components
- Build output directory: dist (standaard)

Tijdens het bouwen wordt de opgegeven versie van de componentenbibliotheek automatisch gekloond en geïntegreerd.

Na configuratie kunt u gemakkelijk componenten gebruiken

Zodra de configuratie voltooid is, is het zeer eenvoudig om componenten te gebruiken.

Maak src/index.ts in de componentenbibliotheek 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 u 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 u een nieuwe versie van de componentenbibliotheek wilt uitbrengen,

Breng wijzigingen aan in de componentenbibliotheek en commit deze
Maak een nieuw tag aan (bijvoorbeeld: v1.1.0)

Werk de package.json van het hoofdproject bij

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

Elk project kan de versie van componenten gebruiken die het nodig heeft.

De ontwikkelingsstroom is ook veilig

Een veilige en efficiënte ontwikkelingsstroom betekent dat je je minder zorgen hoeft te maken.

Ontwikkel nieuwe functies of breng wijzigingen aan in de componentbibliotheek (bijvoorbeeld: feature/new-button branch)
Je kunt die wijzigingen onmiddellijk in je lokale omgeving in het hoofdproject testen en verifiëren
Wanneer de ontwikkeling een bepaald stadium bereikt, maak je een testtag aan (bijvoorbeeld: v1.1.0-test)
Update componentVersion naar de testtag in de testomgevingsbranch van het hoofdproject en deploy naar de testomgeving
Wanneer je hebt bevestigd dat alles goed werkt in de testomgeving, merge je naar de main branch van de componentbibliotheek
Een nieuw versietag maken en de versie van het hoofdproject bijwerken zorgt ervoor dat het in productie wordt doorgevoerd (bijvoorbeeld: v1.1.0)

Het voordeel is dat u componentwijzigingen kunt testen zonder invloed op de productieomgeving!

De productieomgeving van Cloudflare Pages gebruikt de versie van het tag dat is opgegeven in config.componentVersion, dus zolang u geen nieuw tag maakt en config bijwerkt, hebben wijzigingen geen invloed op de productieomgeving. U kunt dus gerust zijn!

■ Maak gebruik van een privérepository van GitHub en aangepaste buildscripts, zonder privépakketten van npm!

■ Door proper beheer van GitHub Token en correcte configuratie van de lokale ontwikkelingomgeving kunnen componenten naadloos worden gedeeld in het hele team!

Wat vindt u hiervan?

Is dit niet ideaal voor kleine tot middelgrote teams of projecten waar kostenefficiëntie prioriteit heeft?

Als uw team of project in de toekomst groeit, kunt u altijd nog overwegen over te stappen op privépakketten van npm. Maar voor nu denk ik dat deze methode al efficiënt genoeg is voor het delen van componenten!

Aanvulling: deze aanpak kan ook worden gebruikt met andere frameworks dan Astro (React, Vue, Svelte, etc.). De configuratiedetails kunnen verschillen, maar de basisaanpak is hetzelfde! U kunt dit buildproces ook aanpassen bij andere hostingservices dan Cloudflare Pages.