🚀 Quick Start - Mi Primer Microfrontend

Objetivo: En 30 minutos tendrás un microfrontend funcional según tu escenario específico

Prerrequisitos: Setup del Entorno completado ✅

Tip

Múltiples caminos: Elige tu escenario para seguir el flujo específico que necesitas.

---

🎯 ¿Cuál es tu escenario?

🧪 Solo Quiero Aprender

Tu situación:

• Experimentar con la arquitectura
• Familiarizarte con el stack
• Pruebas locales sin commits

Tiempo estimado: 20 minutos

👉 Ir al Escenario A

🆕 Empiezo de Cero

Tu situación: - Nuevo proyecto/equipo - Necesitas workspace completo - Quieres toda la estructura base Tiempo estimado: 15 minutos 👉 Ir al Escenario B

➕ Tengo Proyecto Existente

Tu situación:

• Ya tienes workspace funcionando
• Solo necesitas un microfrontend específico
• Quieres copiarlo a tu repo

Tiempo estimado: 10 minutos

👉 Ir al Escenario C

---

🧪 Escenario A: Aprendizaje y Experimentación

Para: Desarrolladores que quieren familiarizarse con la arquitectura

Paso 1: Explorar Ejemplos Existentes

1. Ver estructura actual:

   cd proyecto-vue
   Get-ChildItem @apps/      # Ver microfrontends de ejemplo
   Get-ChildItem packages/   # Ver librerías compartidas

2. Ejecutar ejemplo existente:

   # Si hay ejemplos pre-existentes
   pnpm app-{ejemplo} dev
   # Explorar en http://localhost:5173

3. Inspeccionar código:

   code @apps/{ejemplo}/src/
   # Estudiar: store, componentes, configuración

Paso 2: Crear tu Primer Experimento

1. Generar microfrontend de prueba (en proyecto-vue):

   npx plop
   # Seleccionar: microfrontend-integrado
   # Nombre: mi-experimento
   # Descripción: Prueba de aprendizaje

2. Agregar script temporal: Editar package.json raíz de proyecto-vue:

   {
      "scripts": {
         "app-mi-experimento": "pnpm --filter mi-experimento"
      }
   }

3. Ejecutar y experimentar:

   pnpm install
   pnpm app-mi-experimento dev

Paso 3: Experimentar con Patterns

1. Probar diferentes configuraciones:

   • Cambiar window.__params en el HTML
   • Modificar store para diferentes APIs
   • Experimentar con componentes Vue

2. Crear librería de prueba:

   npx plop
   # Seleccionar: libreria-vue
   # Nombre: vue-mi-experimento

3. Integrar librería en microfrontend:

   • Usar la librería desde el microfrontend
   • Probar hot reload entre packages

Note

Importante: Este código es solo para aprendizaje en proyecto-vue. NO hagas commits. Cuando quieras código real para tu proyecto, usa los Escenarios B o C.

---

🆕 Escenario B: Workspace Completo desde Cero

Para: Equipos que empiezan un proyecto completamente nuevo

Paso 1: Generar Workspace Completo

1. Ir al generador (siempre desde proyecto-vue):

   cd proyecto-vue
   git pull origin main  # Obtener últimas actualizaciones

2. Ejecutar generador:

   npx plop

   Seleccionar: proyecto-completo

3. Completar prompts:

   ? Nombre del proyecto/workspace: mi-empresa-frontend
   ? Descripción del proyecto: Sistema de microfrontends para Mi Empresa
   ? Nombre del equipo: Frontend Team
   ? ¿Incluir package de tipos TypeScript? Sí
   ? ¿Incluir package de utilidades generales? Sí

4. Resultado:

   🎉 ¡Workspace generado exitosamente!
   📁 Ubicación: ./mi-empresa-frontend/

Paso 2: Configurar tu Nuevo Repositorio

1. Copiar workspace a tu repositorio (SIN templates):

   # Crear tu nuevo repositorio
   mkdir /ruta/a/mi-nuevo-repo
   cd /ruta/a/mi-nuevo-repo
   git init
   
   # Copiar SOLO el contenido del workspace generado
   Copy-Item -Recurse ../proyecto-vue/mi-empresa-frontend/* ./

2. Setup inicial:

   pnpm install
   pnpm build

3. Verificar que funciona:

   pnpm lint     # Debe pasar sin errores
   pnpm format   # Debe formatear archivos

Note

Importante: Tu nuevo workspace NO tiene templates. Para agregar más componentes, siempre vuelve a proyecto-vue para generarlos.

Paso 3: Agregar tu Primer Microfrontend

1. Generar microfrontend (volver a proyecto-vue):

   cd ../proyecto-vue  # ← SIEMPRE volver aquí para generar
   npx plop
   # Seleccionar: microfrontend-integrado
   # Nombre: flight-search
   # Descripción: Buscador de vuelos integrado

2. Copiar a tu workspace:

   Copy-Item -Recurse @apps/flight-search ../mi-nuevo-repo/@apps/
   cd ../mi-nuevo-repo

3. Configurar script: Agregar al package.json raíz de tu workspace:

   {
      "scripts": {
         "app-flight-search": "pnpm --filter flight-search"
      }
   }

4. Ejecutar en desarrollo:

   pnpm install
   pnpm app-flight-search dev

5. Verificar funcionamiento:

   • ✅ Abrir http://localhost:5173
   • ✅ Ver título “Products” (ejemplo)
   • ✅ Loading spinner y datos de ejemplo
   • ✅ Console sin errores

Tip

Workflow futuro: Para cada nuevo componente, repite el proceso: generar en proyecto-vue → copiar a tu workspace → configurar script.

---

➕ Escenario C: Agregar Microfrontend Específico

Para: Equipos que ya tienen workspace funcionando y necesitan agregar componentes

Paso 1: Generar en proyecto-vue

1. Ir al generador (siempre desde proyecto-vue):

   cd proyecto-vue
   git pull origin main

2. Generar microfrontend:

   npx plop
   # Seleccionar: microfrontend-integrado
   # Nombre: hotel-booking
   # Descripción: Sistema de reserva de hoteles
   # URLs CDN: usar defaults

3. Verificar generación:

   Get-ChildItem @apps/hotel-booking/
   # Debe mostrar: src/, package.json, vite.config.ts, etc.

Paso 2: Copiar a tu Proyecto Real

1. Copiar microfrontend completo:

   Copy-Item -Recurse @apps/hotel-booking ../mi-proyecto-real/@apps/
   cd ../mi-proyecto-real

2. Agregar script al workspace: Editar package.json raíz de tu proyecto:

   {
      "scripts": {
         "app-hotel-booking": "pnpm --filter hotel-booking"
      }
   }

3. Instalar dependencias:

   pnpm install

4. Desarrollar:

   pnpm app-hotel-booking dev

Paso 3: Personalizar y Adaptar

1. Adaptar configuración: Editar @apps/hotel-booking/.env.development:

   VITE_USE_MOCKS = "true"
   VITE_IS_DEBUG = "true"
   VITE_I18_PATH = "https://test.XXXXX.com/i18n/hotel-booking"
   VITE_API_URL = "https://test-api.XXXXX.com/api"

2. Personalizar lógica de negocio:

   • Adaptar src/stores/productStore.ts a tu dominio
   • Modificar src/components/ProductList.vue según tu UI
   • Actualizar src/global.ts con tus tipos específicos

3. Build para producción:

   pnpm app-hotel-booking build
   # Archivos listos en: @apps/hotel-booking/dist/

Tip

Filosofía clave: proyecto-vue es tu “fábrica de componentes”. Siempre generas ahí y copias a tus proyectos reales. Los templates nunca se desactualizan porque siempre usas la fuente central.

---

🎉 ¡Felicitaciones!

Has completado el Quick Start exitosamente. Según tu escenario, ahora tienes:

✅ Escenario A - Aprendizaje:

• Comprensión de la arquitectura
• Experiencia práctica con el stack
• Conocimiento de patterns y configuraciones
• Preparado para proyectos reales

✅ Escenario B - Workspace Completo:

• Workspace completo funcionando
• Primer microfrontend ejecutándose
• Base sólida para crear más componentes
• Flujo establecido para tu equipo

✅ Escenario C - Microfrontend Específico:

• Componente funcional en tu proyecto real
• Código adaptable a tu dominio específico
• Build optimizado para producción
• Workflow para futuros componentes

Tip

Recordatorio clave: proyecto-vue es tu “fábrica de componentes” centralizada. Los templates siempre están actualizados ahí, nunca se desactualizan en tus proyectos.

---

🔄 Próximos Pasos

Para todos los escenarios:

1. Profundizar en conceptos: 🧠 Conceptos Clave - Arquitectura y filosofía

2. Workflows diarios: 💻 Desarrollo Día a Día - Patrones y herramientas cotidianas

3. Referencia técnica: 📚 Referencias - Configuraciones detalladas

4. Casos específicos: 🌳 Decision Tree - Qué template usar según tu caso

---

🆘 Troubleshooting por Escenario

Escenario A - Aprendizaje

❌ “No puedo hacer commits”

¡Perfecto! Es el comportamiento esperado. Este escenario es solo para experimentos locales en proyecto-vue.

❌ “¿Cómo paso a proyecto real?”

Usa Escenario B (workspace completo) o C (código específico) cuando estés listo.

Escenario B - Workspace Completo

❌ “Cannot find module @pnpmworkspace/…”

cd tu-nuevo-repo
pnpm -r build  # Build packages primero
pnpm app-{nombre} dev

❌ “¿Cómo agrego más componentes?”

# SIEMPRE volver a proyecto-vue para generar
cd ../proyecto-vue
npx plop → microfrontend-integrado
Copy-Item -Recurse @apps/nuevo-componente ../mi-nuevo-repo/@apps/

Escenario C - Código Específico

❌ “Error al copiar componente”

# Verificar que el componente se generó correctamente
Get-ChildItem @apps/mi-componente/
Copy-Item -Recurse @apps/mi-componente ../mi-proyecto-real/@apps/

❌ “TypeScript errors en proyecto real”

# Verificar workspace TypeScript
# VS Code: Ctrl+Shift+P → "TypeScript: Select Version" → "Use Workspace Version"

❌ “¿Componentes desactualizados?”

# Los templates siempre están actualizados en proyecto-vue
cd proyecto-vue
git pull origin main  # Obtener últimas mejoras
npx plop  # Generar con templates actualizados

Tip

Flujo futuro: Cada vez que necesites generar código, ve a proyecto-vue → npx plop → copiar resultado. Los templates nunca se desactualizan porque siempre usas la fuente central.