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 los mismos componentes de UI en múltiples sitios, ¿verdad?

Cuando se utilizan marcos modernos como Astro para optimizar el desarrollo de múltiples sitios, compartir una librería de componentes es muy efectivo. Sin embargo, cuando se comparten componentes como paquetes npm, publicar paquetes privados requiere un plan de pago.

Esta vez te presentamos cómo compartir y gestionar componentes de forma eficiente usando repositorios de GitHub y Cloudflare Pages, sin necesidad de empaquetar con npm.

¿Cuáles son los desafíos del compartir componentes?

Quiero usar los mismos componentes de UI en múltiples sitios de Astro.
Quiero alojar en Cloudflare Pages.
¡Quiero gestionar componentes en repositorios privados de GitHub!
¡Quiero convertir componentes en paquetes npm, pero sin hacerlos públicos!

Así es. Entonces, ¿cuál es la mejor forma de hacerlo?

Resolver con repositorio de GitHub y script de compilación personalizado

Para resolver estos desafíos, pensamos que podría ser útil abordarlos de esta manera.

Crear un repositorio de GitHub para componentes
Usar referencias de archivo en el desarrollo local
Clonar el repositorio de componentes durante la compilación en Cloudflare Pages

Es posible compartir y gestionar componentes sin usar paquetes npm privados.

La implementación se ve así

1. Crear un token de acceso personal de GitHub

Crea un token de acceso personal de GitHub para acceder a repositorios privados.

Inicia sesión en GitHub
Haz clic en el icono de perfil en la esquina superior derecha → Configuración
En la barra lateral izquierda, selecciona «Configuración de desarrollador» → «Tokens de acceso personal» → «Tokens (clásico)»
Haz clic en «Generar nuevo token» → «Generar nuevo token (clásico)»
Otorga los siguientes permisos al token:
- repo - Acceso completo a repositorios privados
Genera el token y guárdalo en un lugar seguro (solo se mostrará una vez)

2. Construcción de 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://$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などの開発依存関係
  }
}

Estos 4 puntos son clave.

Sección config: gestión centralizada de 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 y compilación de componentes
dependencies: referencias a archivos locales para desarrollo

4. Configura tu entorno de desarrollo local

Clona la biblioteca de componentes en el mismo nivel que tu proyecto y úsala mediante referencias de archivo.

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

Los cambios que realices en los componentes durante el desarrollo local se reflejarán inmediatamente en el proyecto principal.

5. Configuración de Cloudflare Pages

La configuración en Cloudflare Pages se realiza aquí.

Configuración de variables de entorno:
- Panel de Pages → your-project → Settings → Environment variables
- Nombre de variable: GITHUB_TOKEN
- Valor: Tu GitHub Personal Access Token generado
Configuración del comando de compilación:
- Panel Pages → your-project → Settings → Build & deployments
- Build command: npm run build-with-components
- Directorio de salida de compilación: dist (predeterminado)

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

Una vez configurado, es fácil usar los componentes

Una vez completada la configuración, usar 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';
// 他のコンポーネントもここでエクスポート

Importe los componentes que desea usar en el proyecto principal.

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

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

¿Cómo se gestiona el versionado?

Cuando desee lanzar una nueva versión de la biblioteca de componentes,

Realice cambios en la biblioteca de componentes e haga commit
Crear una nueva etiqueta (por ejemplo: v1.1.0)

Actualizar package.json del proyecto principal

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

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

El flujo de desarrollo también es seguro

Un flujo de desarrollo seguro y eficiente es algo de lo que estar menos preocupado.

Desarrollar nuevas funciones o realizar mejoras en la biblioteca de componentes (por ejemplo: rama feature/new-button)
Puede probar y verificar esos cambios inmediatamente en el proyecto principal en el entorno local
Cuando el desarrollo ha avanzado a una etapa determinada, cree una etiqueta de prueba (por ejemplo: v1.1.0-test)
En la rama de entorno de prueba del proyecto principal, actualice componentVersion a la etiqueta de prueba e implemente en el entorno de prueba
Una vez que confirme que no hay problemas en el entorno de prueba, fusione con la rama main de la biblioteca de componentes
Al crear una nueva etiqueta de versión y actualizar la versión del proyecto principal, se refleja en producción (por ejemplo: v1.1.0)

¡El punto clave es que puedes probar cambios de componentes sin impactar el entorno de producción!

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

■ ¡Combina repositorios privados de GitHub con scripts de compilación personalizados, sin necesidad de usar paquetes privados de npm!

■ Con una gestión adecuada del token de GitHub y la configuración correcta del entorno de desarrollo local, ¡logra un intercambio de componentes fluido en todo el equipo!

¿Qué te parece?

¿No te parece ideal para equipos pequeños y medianos, o proyectos que priorizan la eficiencia de costos?

Si en el futuro tu equipo o proyecto crece, siempre puedes considerar migrar a paquetes privados de npm. Pero por ahora, este método es suficientemente eficiente para lograr un intercambio de componentes productivo. ¡Lo creemos así!

Nota: Este enfoque también es aplicable en otros frameworks más allá de Astro (React, Vue, Svelte, etc.). Los detalles de configuración pueden variar, pero el concepto básico es el mismo. ¡También puedes personalizar el proceso de compilación de manera similar en servicios de hosting distintos a Cloudflare Pages!