Cómo compartir componentes privados de Astro sin usar npm

Gestión compartida de componentes

En el desarrollo web, a veces surge la necesidad de reutilizar el mismo componente de UI en varios sitios web, ¿verdad?

Al desarrollar varios sitios con un framework moderno como Astro, compartir una biblioteca de componentes es muy eficaz para mejorar la eficiencia. Sin embargo, si compartes los componentes como paquetes de npm, puede que necesites un plan de pago para publicar paquetes privados.

En este artículo le presentamos cómo compartir y gestionar componentes de forma eficiente usando un repositorio de GitHub y Cloudflare Pages, sin empaquetarlos con npm.

¿Cuál es el problema de compartir componentes?

¡Quiero usar el mismo componente de UI en varios sitios de Astro!
¡Quiero alojarlo en Cloudflare Pages!
¡Quiero gestionar componentes en un repositorio privado de GitHub!
Quiero empaquetar los componentes como un paquete npm, ¡pero no quiero publicarlos!

Así es la situación. Entonces, ¿qué sería lo mejor?

Se resuelve con un repositorio de GitHub y un script de compilación personalizado

Para resolver estos desafíos, propongo el siguiente enfoque.

Crear un repositorio de GitHub para los componentes
Usar referencias a archivos en el desarrollo local
En el entorno de Cloudflare Pages, clonar el repositorio de componentes durante la compilación

Sin usar paquetes privados de npm, es posible compartir y gestionar componentes.

Así se implementa

1. Crear un GitHub Personal Access Token

Crea un GitHub Personal Access Token para acceder a repositorios privados.

Inicia sesión en GitHub
Haz clic en el icono de tu perfil en la esquina superior derecha → Settings
En la barra lateral izquierda, selecciona "Developer settings" → "Personal access tokens" → "Tokens (classic)"
Haz clic en "Generate new token" → "Generate new token (classic)"
Concede al token los siguientes permisos:
- repo: acceso completo a repositorios privados
Genera el token y guárdalo en un lugar seguro (solo se muestra una vez).

2. Construir la biblioteca de componentes

Crea un repositorio de GitHub para los componentes (por ejemplo: github.com/your-username/ui-components).

package.json de la biblioteca de componentes

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

3. Configura el proyecto principal

Configura el package.json del proyecto principal que utilizará los componentes.

package.json del proyecto 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などの開発依存関係
  }
}

Estos cuatro puntos son clave.

Sección config: gestiona centralmente la información de la biblioteca de componentes
Script setup-components: clona los componentes desde GitHub durante la compilación
Script build-with-components: comando que combina la configuración de los componentes y la compilación
dependencies: referencias a archivos para el desarrollo local

4. Configurar el entorno de desarrollo local

Clona la biblioteca de componentes en el mismo nivel que el proyecto y utilízala mediante referencias de archivo.

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

Si modificas un componente durante el desarrollo local, el cambio se reflejará de inmediato en el proyecto principal.

5. Configurar Cloudflare Pages

A continuación se muestra la configuración en Cloudflare Pages.

Configuración de variables de entorno:
- Panel de Pages → your-project → Settings → Environment variables
- Nombre de la variable: GITHUB_TOKEN
- Valor: el GitHub Personal Access Token que creaste
Configuración del comando de compilación:
- Panel de Pages → your-project → Settings → Build & deployments
- Build command: npm run build-with-components
- Build output directory: dist (predeterminado)

Durante la compilación, la biblioteca de componentes de la versión especificada se clona e integra automáticamente.

Uso sencillo de componentes una vez completada la configuración

Una vez completada la configuración, usar los componentes es muy sencillo.

Cree src/index.ts en la biblioteca de componentes y exporte los componentes.

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

En el proyecto principal, importe los componentes que desee utilizar.

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

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

¿Cómo se gestionan las versiones?

Cuando quiera publicar una nueva versión de la biblioteca de componentes,

realice los cambios en la biblioteca de componentes y haga commit.
Crea una nueva etiqueta (por ejemplo: v1.1.0)

Actualiza el package.json del proyecto principal

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

Cada proyecto puede usar la versión de los componentes que necesite.

Un flujo de desarrollo seguro

Un flujo de desarrollo seguro y eficiente te permite despreocuparte de muchos detalles, ¡y eso es una gran ventaja!

Desarrolla y modifica nuevas funciones en la biblioteca de componentes (por ejemplo: rama feature/new-button)
Puedes probar y verificar esos cambios de inmediato en el proyecto principal, en tu entorno local
Cuando el desarrollo alcance una etapa determinada, crea una etiqueta de prueba (por ejemplo: v1.1.0-test)
En la rama del entorno de pruebas del proyecto principal, actualiza componentVersion a la etiqueta de prueba y despliega en el entorno de pruebas
Una vez confirmado que todo funciona correctamente en el entorno de pruebas, fusiona la rama main de la biblioteca de componentes
Se publica en producción creando una nueva etiqueta de versión y actualizando la versión del proyecto principal (por ejemplo: v1.1.0)

¡Lo mejor es que puedes probar los cambios de los componentes sin afectar al entorno de producción!

El entorno de producción de Cloudflare Pages utiliza la versión de la etiqueta especificada en config.componentVersion, así que los cambios no afectarán a producción mientras no crees una nueva etiqueta y actualices config. ¡Puedes estar tranquilo!

■ Sin usar paquetes privados de npm, combina un repositorio privado de GitHub con un script de compilación personalizado.

■ Con una gestión adecuada del token de GitHub y una configuración correcta del entorno de desarrollo local, los componentes se comparten sin fricciones en todo el equipo.

¿Qué le parece?

¿No es esta solución ideal para equipos pequeños o medianos y proyectos que priorizan la rentabilidad?

Si el equipo o los proyectos crecen en el futuro, también se puede considerar migrar a paquetes privados de npm, pero, por ahora, creo que este método permite compartir componentes de forma muy eficiente.

Nota: También es aplicable a otros frameworks distintos de Astro (como React, Vue o Svelte). Los detalles de la configuración pueden variar, pero el enfoque básico es el mismo. Además, puedes personalizar el proceso de compilación de forma similar en otros servicios de hosting distintos de Cloudflare Pages.