Saltar a contenido

Instalacion

Esta guia te acompana en la configuracion del monorepo CyberEco Hub para desarrollo local.

Requisitos Previos

Antes de comenzar, asegurate de tener instalado lo siguiente:

Herramienta Version Verificar
Node.js >= 18 node --version
npm >= 10 npm --version
Git Ultima git --version

Gestion de versiones de Node.js

Recomendamos usar nvm o fnm para gestionar las versiones de Node.js. El proyecto requiere Node.js 18 o superior, y el CI ejecuta pruebas con Node.js 18 y 20.

Clonar el Repositorio

git clone https://github.com/cyber-eco/cybereco-hub.git
cd cybereco-hub

Instalar Dependencias

npm ci

Esto instala todas las dependencias del workspace para los 4 paquetes npm y la aplicacion Hub en un solo comando. El flag ci garantiza una instalacion limpia y reproducible desde package-lock.json.

Workspaces del monorepo

CyberEco Hub utiliza npm workspaces para gestionar multiples paquetes en un solo repositorio. La configuracion de workspaces en el package.json raiz incluye packages/* y apps/*.

Configuracion del Entorno

La aplicacion Hub requiere configuracion de Firebase. Copia el archivo de entorno de ejemplo y completa tus valores:

cp apps/hub/.env.example apps/hub/.env

Luego edita apps/hub/.env con las credenciales de tu proyecto Firebase:

apps/hub/.env
# Publicas (expuestas al cliente via import.meta.env.PUBLIC_*)
PUBLIC_HUB_URL=http://localhost:4321
PUBLIC_FIREBASE_API_KEY=tu-api-key
PUBLIC_FIREBASE_AUTH_DOMAIN=tu-proyecto.firebaseapp.com
PUBLIC_FIREBASE_PROJECT_ID=tu-id-de-proyecto
PUBLIC_FIREBASE_STORAGE_BUCKET=tu-proyecto.appspot.com
PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
PUBLIC_FIREBASE_APP_ID=1:123456789:web:abc123

# Solo servidor (NO expuestas al cliente)
JWT_SECRET=un-secreto-aleatorio-fuerte-de-al-menos-32-caracteres

Prefijos de variables de entorno

Las variables con prefijo PUBLIC_ se exponen al codigo del lado del cliente mediante import.meta.env.PUBLIC_* de Astro. El JWT_SECRET es solo del servidor y nunca debe exponerse al navegador.

Referencia de Variables

Variable Requerida Descripcion
PUBLIC_HUB_URL Si URL base de la aplicacion Hub (ej. http://localhost:4321 para desarrollo)
PUBLIC_FIREBASE_API_KEY Si Clave API Web de Firebase desde la Consola de Firebase
PUBLIC_FIREBASE_AUTH_DOMAIN Si Dominio de Firebase Auth (ej. tu-proyecto.firebaseapp.com)
PUBLIC_FIREBASE_PROJECT_ID Si ID del proyecto Firebase
PUBLIC_FIREBASE_STORAGE_BUCKET Si Bucket de Firebase Storage (ej. tu-proyecto.appspot.com)
PUBLIC_FIREBASE_MESSAGING_SENDER_ID Si ID del remitente de Firebase Cloud Messaging
PUBLIC_FIREBASE_APP_ID Si ID de la aplicacion Firebase
JWT_SECRET Si Clave secreta para firmar JWTs (tokens de autenticacion del servidor)

Obtener credenciales de Firebase

  1. Ve a la Consola de Firebase
  2. Crea o selecciona un proyecto
  3. Ve a Configuracion del Proyecto > General
  4. En Tus apps, haz clic en el icono web (</>) para agregar una app web
  5. Copia los valores de configuracion del objeto firebaseConfig generado

Compilar

Compila los 5 paquetes (4 paquetes npm + aplicacion Hub) en orden topologico:

npm run build

Turborepo orquesta la compilacion, asegurando que los paquetes se compilen en orden de dependencias:

@cyber-eco/types          (se compila primero - cero deps)
       |
       +------------------+
       |                  |
       v                  v
@cyber-eco/firebase   @cyber-eco/auth     (se compilan en paralelo)
       |                  |
       +------------------+
       |
       v
@cyber-eco/services       (se compila despues de firebase + auth)
       |
       v
  apps/hub               (se compila al final)

Herramientas de compilacion

  • Paquetes: Compilados con tsup produciendo salida dual ESM/CJS
  • Aplicacion Hub: Compilada con Astro + Vite
  • Orquestacion: Turborepo con configuracion turbo.json

Desarrollo

Inicia el servidor de desarrollo del Hub (compila las dependencias primero):

npm run dev

El servidor de desarrollo se inicia en http://localhost:4321 con reemplazo de modulos en caliente (HMR) habilitado.

Pruebas

Ejecuta todas las pruebas del monorepo:

npm run test

Las pruebas usan Vitest y no requieren emuladores de Firebase -- todas las pruebas de servicios de dominio usan el MockStorageAdapter de @cyber-eco/services/testing.

Verificacion de Tipos

Ejecuta la verificacion estricta de TypeScript en todos los paquetes:

npm run type-check

Comandos Adicionales

Comando Descripcion
npm run lint Ejecutar ESLint en todos los paquetes
npm run clean Eliminar todos los artefactos de compilacion y node_modules
npm run changeset Crear un nuevo changeset para versionado
npm run version-packages Aplicar changesets para incrementar versiones de paquetes
npm run publish-packages Compilar y publicar paquetes via Changesets

Siguientes Pasos