Comment partager des composants Astro privés sans npm

Gestion partagée des composants

Dans le développement web, il arrive parfois que l'on souhaite réutiliser les mêmes composants UI sur plusieurs sites, n'est-ce pas ?

Pour gagner en efficacité dans le développement de plusieurs sites avec un framework moderne comme Astro, le partage d'une bibliothèque de composants est très utile. Cependant, lorsque les composants sont partagés sous forme de paquets npm, la publication de paquets privés nécessite un forfait payant, ce qui peut poser problème.

Dans cet article, nous vous présentons une méthode pour partager et gérer efficacement des composants sans les empaqueter avec npm, en utilisant un dépôt GitHub et Cloudflare Pages !

Les défis du partage de composants !?

Utiliser les mêmes composants UI sur plusieurs sites Astro !
Héberger sur Cloudflare Pages !
Je souhaite gérer mes composants dans un dépôt GitHub privé !
Je voudrais empaqueter mes composants sous forme de paquet npm, mais sans les rendre publics !

Voilà à peu près l'idée. Alors, comment procéder ?

Une solution avec un dépôt GitHub et un script de build personnalisé

Pour résoudre ces difficultés, je propose l'approche suivante.

Créer un dépôt GitHub dédié aux composants
Utiliser des références de fichiers pour le développement en local
Dans l'environnement Cloudflare Pages, cloner le dépôt de composants au moment du build

Sans recourir à un paquet npm privé, il devient possible de partager et de gérer les composants.

Mise en œuvre

1. Créer un GitHub Personal Access Token

Créez un GitHub Personal Access Token pour accéder aux dépôts privés.

Se connecter à GitHub
Cliquez sur l'icône de profil en haut à droite → Settings
Dans la barre latérale de gauche, sélectionnez « Developer settings » → « Personal access tokens » → « Tokens (classic) »
Cliquez sur « Generate new token » → « Generate new token (classic) »
Accordez au token les autorisations suivantes :
- repo - Accès complet aux dépôts privés
Générez le token et conservez-le dans un endroit sûr (il ne sera affiché qu'une seule fois)

2. Construction de la bibliothèque de composants

Créez un dépôt GitHub pour les composants (par exemple : github.com/your-username/ui-components).

Le package.json de la bibliothèque de composants

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

3. Configurer le projet principal

Configurez le package.json du projet principal qui utilise les composants.

Le package.json du projet principal

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

Les quatre points suivants sont essentiels.

Section config : gestion centralisée des informations de la bibliothèque de composants
Script setup-components : clonage des composants depuis GitHub lors du build
Script build-with-components : commande combinant la configuration des composants et le build
dependencies : références de fichiers locaux pour le développement

4. Configurer l'environnement de développement local

Clonez la bibliothèque de composants au même niveau que le projet et utilisez-la via des références de fichiers.

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

Lorsque vous modifiez un composant pendant le développement local, la modification est immédiatement répercutée dans le projet principal.

5. Configurer Cloudflare Pages

Voici la configuration à effectuer dans Cloudflare Pages.

Configuration des variables d'environnement :
- Tableau de bord Pages → your-project → Settings → Environment variables
- Nom de la variable : GITHUB_TOKEN
- Valeur : le GitHub Personal Access Token que vous avez créé
Configuration de la commande de build :
- Tableau de bord Pages → your-project → Settings → Build & deployments
- Build command: npm run build-with-components
- Répertoire de sortie du build : dist (par défaut)

Lors du build, la bibliothèque de composants dans la version spécifiée est automatiquement clonée et intégrée.

Utilisez facilement les composants une fois la configuration terminée

Une fois la configuration terminée, utiliser les composants est très simple.

Créez src/index.ts dans la bibliothèque de composants et exportez les composants.

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

Dans le projet principal, importez les composants que vous souhaitez utiliser.

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

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

Et la gestion des versions ?

Lorsque vous souhaitez publier une nouvelle version de la bibliothèque de composants,

apportez vos modifications à la bibliothèque de composants et effectuez un commit
Créer un nouveau tag (par exemple : v1.1.0)

Mettre à jour le package.json du projet principal

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

Chaque projet peut utiliser la version du composant dont il a besoin.

Un flux de développement sécurisé

Un flux de développement sûr et efficace vous permet de vous concentrer sur l'essentiel, sans vous soucier de détails superflus.

Développer de nouvelles fonctionnalités ou effectuer des modifications dans la bibliothèque de composants (par exemple : branche feature/new-button)
Tester et vérifier ces modifications immédiatement dans le projet principal, depuis votre environnement local
Une fois le développement arrivé à une étape suffisamment avancée, créer un tag de test (par exemple : v1.1.0-test)
Dans la branche de l'environnement de test du projet principal, mettre à jour componentVersion avec le tag de test, puis déployer sur l'environnement de test
Une fois la validation effectuée dans l'environnement de test, fusionner dans la branche main de la bibliothèque de composants
La mise en production s'effectue en créant un nouveau tag de version et en mettant à jour la version du projet principal (ex. : v1.1.0).

Le point fort : tester les modifications de composants sans aucun impact sur la production !

L'environnement de production de Cloudflare Pages utilise la version du tag spécifiée dans config.componentVersion. Tant que vous ne créez pas de nouveau tag et ne mettez pas à jour config, vos modifications n'affecteront pas la production : vous pouvez donc travailler l'esprit tranquille !

■ Sans recourir aux packages privés npm, combinez un dépôt GitHub privé et un script de build personnalisé !

■ Grâce à une gestion appropriée des tokens GitHub et à une configuration correcte de l'environnement de développement local, le partage de composants devient fluide pour toute l'équipe !

Qu'en pensez-vous ?

Cette approche ne convient-elle pas parfaitement aux petites et moyennes équipes, ainsi qu'aux projets où le rapport coût-efficacité est essentiel ?

Si l'équipe ou le projet venait à grandir, il serait toujours possible d'envisager un passage aux packages privés npm. Pour l'instant, cette méthode permet déjà un partage de composants efficace !

Remarque : cette méthode fonctionne aussi avec d'autres frameworks qu'Astro (React, Vue, Svelte, etc.). Les détails de configuration peuvent varier, mais l'approche de base reste la même. Vous pouvez également personnaliser le processus de build de la même manière avec d'autres hébergeurs que Cloudflare Pages !