🧠 Conceptos Clave

Objetivo: Comprender los principios fundamentales que guían nuestro stack de frontend y las decisiones arquitectónicas

🏗️ Filosofía de Desarrollo: “Un Repositorio, Múltiples Funciones”

El Concepto Central: proyecto-vue como “Fábrica de Componentes”

graph TD
    A[proyecto-vue] --> B[🧪 Laboratorio de Aprendizaje]
    A --> C[🏗️ Generador de Workspaces]
    A --> D[🎨 Fábrica de Componentes]

    B --> E[Experimenta sin commits]
    C --> F[Workspace completo para equipos nuevos]
    D --> G[Microfrontends específicos]
    D --> H[Librerías específicas]

    F --> I[Tu Repositorio Nuevo]
    G --> J[Tu Repositorio Existente]
    H --> J

    style A fill:#e1f5fe
    style D fill:#f3e5f5
    style I fill:#e8f5e8
    style J fill:#e8f5e8

¿Por qué Esta Arquitectura?

Problema tradicional:

❌ Cada equipo crea su propia configuración
❌ Templates se desactualizan rápidamente
❌ Inconsistencias entre proyectos
❌ Onboarding lento y repetitivo

Nuestra solución:

✅ Una sola fuente de verdad para configuraciones
✅ Templates siempre actualizados en proyecto-vue
✅ Consistencia automática entre todos los equipos
✅ Onboarding acelerado con patrones probados

🎯 Arquitectura de Microfrontends

Por qué Microfrontends (No SPAs Tradicionales)

El contexto real:

Aplicaciones ASP.NET monolíticas existentes en producción
No podemos reescribir todo de una vez
Necesitamos modernización gradual sin romper nada
Múltiples equipos trabajando en paralelo

Nuestra estrategia:

graph TD
    A[Usuario navega a ASP.NET App] --> B[Página renderiza HTML servidor]
    B --> C[Script carga microfrontend específico]
    C --> D[Vue monta en elemento designado]
    D --> E[Microfrontend recibe datos via window.__params]
    E --> F[Vue app independiente funcionando]
    F --> G[Usuario interactúa solo con esa sección]

    style C fill:#e1f5fe
    style E fill:#f3e5f5
    style F fill:#e8f5e8

Características clave:

🏠 Host-Guest Pattern: El microfrontend es “invitado” en una página ASP.NET existente
📡 Comunicación unidireccional: Host → Microfrontend via window.__params
🎯 Montaje específico: Solo en elementos designados (#main, etc.)
📦 Carga bajo demanda: Se descarga solo cuando la página lo requiere
⚡ Hidratación parcial: Solo esa sección es reactiva, el resto sigue siendo servidor

Diferencias con SPAs Tradicionales

Aspecto	SPA Tradicional	Nuestros Microfrontends
Routing	Client-side routing completo	Sin routing, montaje en elemento específico
Inicialización	Controla toda la página	Solo su sección asignada
Datos iniciales	Fetch desde cliente	Recibe via `window.__params`
SEO	Problemas de hidratación	ASP.NET maneja SEO
Deploy	Aplicación completa	Solo el JS del microfrontend

📦 Arquitectura del Monorepo

La Estructura Inteligente

📁 proyecto-vue/
├── 📁 @apps/                    # 🎯 Microfrontends (productos finales)
│   ├── 📁 flight-search/        # Buscador de vuelos
│   ├── 📁 hotel-booking/        # Reserva de hoteles
│   └── 📁 tu-nuevo-micro/       # Tu próximo microfrontend
├── 📁 packages/                 # 📚 Librerías compartidas
│   ├── 📁 types/               # Tipos TypeScript globales
│   ├── 📁 utils/               # Utilidades puras (sin Vue)
│   ├── 📁 vue-utils/           # Utilidades específicas de Vue
│   └── 📁 vue-modal/           # Componentes compartidos
├── 📁 plop-templates/          # 🎨 Fábrica de componentes
│   ├── 📁 proyecto-completo/   # Template workspace completo
│   ├── 📁 microfrontend-integrado/
│   └── 📁 libreria-vue/
└── 📄 pnpm-workspace.yaml      # ⚙️ Configuración del workspace

Principios de Separación

🚀 Propósito: Microfrontends completos listos para producción

Cada uno resuelve un problema de negocio específico
Build independiente optimizado para CDN
No deben depender de otras apps
Pueden usar todos los packages internos (@pnpmworkspace/*)

👥 Ownership:

Un equipo/feature específico es responsable
Desarrollo y mantenimiento independiente
Decisiones técnicas autónomas dentro de estándares

🚀 Deploy:

Independiente a CDN por separado
Versionado propio (flight-search-v1.2.3.js)
Rollback granular sin afectar otros microfrontends

🎨 Propósito: Generación automática de código consistente

Templates siempre actualizados con mejores prácticas
Configuraciones probadas en producción
Eliminación de setup manual propenso a errores

🔧 Mantenimiento:

Equipo de arquitectura actualiza templates
Mejoras automáticas para todos los equipos
Feedback loop desde experiencia real de proyectos

🚀 Uso:

Solo desde proyecto-vue con npx plop
Nunca se copian a otros workspaces
Siempre actualizados con git pull

Beneficios del Monorepo

Para Desarrollo:

✅ Refactoring cross-project automático
✅ Type safety entre packages y apps
✅ Hot reload entre dependencies internas
✅ Consistencia de versiones con catalog

Para Deploy:

✅ Apps independientes - cada una se despliega por separado
✅ Rollback granular - solo la app con problemas
✅ CDN optimizado - chunks compartidos entre microfrontends
✅ Versionado independiente por microfrontend

🎯 Patrones de Comunicación

1. Host → Microfrontend

Via window.__params (patrón principal):

// El host ASP.NET establece parámetros
window.__params = {
   userId: "12345",
   language: "es-MX",
   apiBaseUrl: "https://api.XXXXX.com",
   theme: "dark",
};

// El microfrontend los consume
const params = window.__params || {};
const userId = params.userId;

Cuándo usar:

✅ Datos de inicialización del microfrontend
✅ Configuración del usuario (idioma, tema)
✅ URLs de APIs específicas del entorno
✅ Tokens de autenticación

2. Microfrontend → Host

Via eventos custom (cuando sea necesario):

// Microfrontend notifica al host
const event = new CustomEvent("microfrontend:action", {
   detail: { action: "navigate", url: "/next-page" },
});
window.dispatchEvent(event);

// Host escucha y reacciona
window.addEventListener("microfrontend:action", (event) => {
   if (event.detail.action === "navigate") {
      window.location.href = event.detail.url;
   }
});

Cuándo usar:

✅ Navegación fuera del microfrontend
✅ Actualización de estado global (carrito, usuario)
✅ Notificaciones al host sobre cambios importantes

3. Entre Microfrontends

Via estado compartido (evitar cuando sea posible):

// Package compartido para estado global
export const globalStore = reactive({
   cart: [],
   user: null,
});

// Microfrontend A modifica
globalStore.cart.push(item);

// Microfrontend B reacciona
watch(
   () => globalStore.cart,
   (newCart) => {
      // Actualizar UI
   },
);

Cuándo usar:

✅ Estado realmente compartido (carrito, usuario)
❌ Evitar para comunicación directa entre microfrontends
⚠️ Usar con cuidado para mantener independencia

🏭 El Concepto de “Fábrica de Componentes”

¿Por qué proyecto-vue es una “Fábrica”?

Analogía Industrial:

graph LR
    A[🏭 Fábrica proyecto-vue] --> B[Templates Actualizados]
    B --> C[Configuraciones Probadas]
    C --> D[Mejores Prácticas]
    D --> E[🎁 Componente Listo]
    E --> F[📦 Copiar a Proyecto Real]

    style A fill:#e1f5fe
    style E fill:#f3e5f5
    style F fill:#e8f5e8

Características de la fábrica:

🔄 Siempre actualizada: git pull trae las últimas mejoras
🏭 Producción en masa: Genera múltiples tipos de componentes
🛡️ Control de calidad: Templates probados en producción
📋 Estandarización: Mismas configuraciones para todos
⚡ Eficiencia: De idea a código funcionando en minutos

Workflow de la Fábrica

graph TD
    A[💡 Necesidad de Componente] --> B[🏭 ir a proyecto-vue]
    B --> C[📋 npx plop]
    C --> D[⚙️ Configurar según necesidad]
    D --> E[🎁 Componente generado]
    E --> F[📦 Copiar a proyecto real]
    F --> G[🔧 Personalizar para dominio específico]
    G --> H[🚀 Desarrollar y desplegar]

    style B fill:#e1f5fe
    style E fill:#f3e5f5
    style F fill:#e8f5e8

Ventajas del modelo fábrica:

🎯 Consistencia: Todos los componentes siguen los mismos patrones
📈 Escalabilidad: Pueden generar componentes múltiples equipos sin coordinación
🔄 Evolución: Las mejoras se propagan automáticamente a nuevas generaciones
🚀 Velocidad: Setup de semanas se reduce a minutos
🛡️ Calidad: Configuraciones probadas eliminan errores comunes

🎯 Stack Decisions y Filosofía

¿Por qué Vue 3 + Composition API?

Decisiones técnicas:

✅ Composition API: Mejor organización del código que Options API
✅ TypeScript nativo: Inferencia automática sin configuración extra
✅ Bundle size: Más pequeño que React para microfrontends
✅ Learning curve: Más fácil para equipos mixtos

En el contexto de microfrontends:

✅ Tree shaking: Solo código usado en cada microfrontend
✅ Performance: Arranque rápido para montaje dinámico
✅ Flexibilidad: Se adapta bien a diferentes hosts

¿Por qué Pinia?

✅ Composition API nativo: Integración perfecta con Vue 3
✅ TypeScript first: Sin configuración adicional de tipos
✅ DevTools: Debugging superior para microfrontends
✅ SSR ready: Aunque no lo usemos, mantiene opciones abiertas

¿Por qué Vite?

✅ Hot Module Reload: Desarrollo ultrarrápido para iteración
✅ ES modules nativo: Mejor performance que bundlers tradicionales
✅ Plugin ecosystem: Integración perfecta con Vue + TypeScript
✅ Build optimization: Tree shaking y code splitting automático

¿Por qué pnpm + Workspace?

✅ Disk efficiency: Hard links reducen espacio significativamente
✅ Monorepo nativo: Sin configuración adicional
✅ Catalog feature: Versiones centralizadas de dependencies críticas
✅ Performance: Installs más rápidos que npm/yarn

💡 Principios de Desarrollo

1. 🧩 Composition API First

// ✅ Así escribimos componentes
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue';
import { useProductStore } from '@/stores/productStore';

const productStore = useProductStore();
const searchQuery = ref('');

const filteredProducts = computed(() =>
  productStore.products.filter(p =>
    p.name.toLowerCase().includes(searchQuery.value.toLowerCase())
  )
);

onMounted(async () => {
  await productStore.fetchProducts();
});
</script>

2. 📝 TypeScript Estricto

// ✅ Tipos explícitos y strict mode
interface Product {
   id: string;
   name: string;
   price: number;
   available: boolean;
}

// ✅ Funciones tipadas
const formatPrice = (price: number, currency: string = "MXN"): string => {
   return new Intl.NumberFormat("es-MX", {
      style: "currency",
      currency,
   }).format(price);
};

3. 🔗 Design by Contract

// ✅ Interfaces claras entre microfrontend y host
interface WindowParams {
   userId: string;
   language: "es-MX" | "en-US";
   apiBaseUrl: string;
   theme?: "light" | "dark";
}

// ✅ Validación de contratos
const validateParams = (params: unknown): params is WindowParams => {
   return (
      typeof params === "object" &&
      params !== null &&
      "userId" in params &&
      "language" in params &&
      "apiBaseUrl" in params
   );
};

4. 📦 Package Boundaries

// ✅ Separación clara de responsabilidades
import { ApiClient } from "@pnpmworkspace/utils/http"; // Sin Vue
import { useI18n } from "@pnpmworkspace/vue-utils"; // Con Vue
import type { Product } from "@pnpmworkspace/types"; // Solo tipos

🔄 Próximos Pasos

Ahora que entiendes los conceptos fundamentales:

Práctica: 💻 Desarrollo Día a Día - Workflows cotidianos con estos conceptos
Decisiones: 🌳 Decision Tree - Aplicar conceptos a casos específicos
Arquitectura avanzada: 🏗️ Arquitectura y Patrones - Patrones complejos y casos de estudio
Referencia técnica: 📚 Referencias - Implementación detallada de estos conceptos