Cuando una empresa usa SAP Business One y empieza a construir sus propias aplicaciones, lo primero que pasa es que cada una se conecta a SAP por su cuenta. La de ventas consulta clientes, la de compras consulta proveedores, la de recursos humanos consulta empleados. Cada una con sus credenciales, sus consultas y su forma de manejar los errores.

Con dos aplicaciones se puede vivir así. Con diecisiete, no. En la plataforma que lidero ninguna aplicación habla con SAP directamente, y cuento cómo está armado y qué fui aprendiendo al integrarlo.

Una sola puerta hacia SAP

Toda la comunicación con SAP pasa por un gateway: un servicio en .NET que es el único que tiene las credenciales de SAP. Por dentro usa dos caminos:

• El Service Layer, la API oficial de SAP Business One, para crear documentos y para las lecturas estándar.
• Lectura directa a HANA, con procedimientos almacenados, para las consultas pesadas que por Service Layer tomarían muchas llamadas.

Y tampoco las aplicaciones llaman al gateway. Solo lo llama el backend del portal, y cada módulo le pide los datos al portal:

 módulo (ventas, compras, rrhh…)
        │  token del usuario
        ▼
 backend del portal ──── tablas espejo (maestros)
        │  mismo token
        ▼
 gateway SAP  (único con credenciales)
        │
        ▼
 SAP Business One  (Service Layer + HANA)

El token del usuario viaja en cada salto. Así el gateway sabe quién pidió cada cosa, y ningún módulo necesita una cuenta de servicio de SAP.

Los maestros se copian, no se consultan

La decisión que más ordenó todo fue esta: los maestros de SAP (clientes, empleados, artículos, proveedores, cuentas contables, departamentos) se sincronizan en la base de datos del portal como tablas espejo. Los módulos leen esas tablas a través de la API del portal. Nunca consultan SAP en vivo para un maestro.

La sincronización tiene un solo punto de entrada por maestro, un POST /sync que es lo único que llama al gateway. Se dispara de dos formas:

• Con un botón "Sincronizar con SAP" en la configuración del portal, solo para administradores.
• Con una tarea programada todas las madrugadas, que corre todos los maestros en secuencia. Si uno falla, los demás siguen.

Por dentro es un upsert por lotes, y lo que desaparece de SAP se marca como inactivo en vez de borrarse, porque puede haber registros en el portal que todavía apuntan a él. La corrida completa, unos 35 mil registros, toma menos de un minuto.

¿Por qué copiar en lugar de consultar?

• Velocidad. Un buscador de clientes no puede esperar a SAP en cada tecla.
• Disponibilidad. Si SAP está en mantenimiento, el portal sigue funcionando con los datos de la noche anterior.
• Un solo lugar para corregir. Si cambia cómo se lee un maestro, se cambia en la sincronización y todos los módulos lo reciben igual.

En vivo solo va lo que tiene que estar al segundo: el stock, el costo de un artículo, el tipo de cambio y la creación de documentos.

Para que esto se mantenga, quedó escrito como regla, con el patrón paso a paso para agregar un maestro nuevo: el endpoint en el gateway, la tabla espejo y su sincronización en el portal, la pantalla con el botón, y el módulo leyendo del portal. Cualquiera del equipo puede agregar uno siguiendo esos pasos.

Lo que aprendí integrando

El Service Layer corta en 20 sin avisar

Una consulta pedía 100 órdenes y llegaban 20. El Service Layer pagina de a 20 por defecto y deja el resto detrás de un @odata.nextLink. No da error ni advertencia, y el count de la respuesta sí trae el total real. Lo descubrimos porque un usuario decía que sus órdenes no estaban en SAP, cuando en realidad estaban en la página dos.

Hay que pedir el tamaño de página explícitamente (la cabecera Prefer: odata.maxpagesize) o seguir el nextLink. Y del lado de quien pagina, la condición de corte tiene que ser el count, no "el lote vino más chico de lo que pedí", porque con este comportamiento eso corta en la primera vuelta.

DocTotal no está en la moneda del documento

En los documentos de SAP Business One, DocTotal es el total en moneda local. DocCurrency dice en qué moneda se emitió. Mostrar DocTotal con el símbolo de DocCurrency hacía que una orden en dólares apareciera con el monto en soles, o sea más del triple.

El importe en la moneda del documento es DocTotalFc, pero cuando el documento está en moneda local SAP lo deja en 0, y un 0 se puede leer como "cero dólares". Por eso el gateway lo publica como null en ese caso, y quien lo consume usa DocTotal cuando no hay otro. Lo llamamos "moneda extranjera" y no "dólares", porque una parte de las compras están en euros.

Hubo un segundo tropiezo con esto mismo: el Service Layer solo devuelve los campos que pides en el $select. Agregamos DocTotalFc al modelo pero no a la lista de campos de la consulta, así que llegaba vacío siempre. Eso no lo detecta el compilador, solo se ve llamando a SAP.

Un error de validación disfrazado de caída

Una alerta de errores 5xx sonó un día por varios 502 seguidos. No era SAP caído: alguien había pedido un costeo sin elegir cliente, el gateway respondió 400 diciendo que faltaba el cliente, y la función que hacía las lecturas convertía cualquier respuesta no exitosa en 502. Las escrituras sí propagaban bien el 400, las lecturas no.

Ese error tenía dos costos: el usuario veía "SAP no responde" cuando el problema era un campo vacío, y la métrica que dispara las alertas se llenaba de falsos 5xx. Ahora las lecturas propagan los 400, 409 y 422 tal cual, con el mensaje del backend.

El SQL de SAP también es código

Los procedimientos almacenados que lee el gateway se crearon directamente en HANA y no estaban en ningún repositorio. Y el mapeo de sus resultados es tolerante a propósito: busca las columnas por nombre, y si una columna cambia de nombre, el campo llega null o 0 sin ningún error.

O sea, alguien podía cambiar un procedimiento y una pantalla empezaba a mostrar ceros sin que nada fallara. La regla que acordamos: el SQL vive con el código que se rompe si cambia. Cada procedimiento que llama el gateway se versiona en su repositorio, en el mismo cambio que el código que lo lee.

Qué haría distinto si empezara hoy

• Versionar el SQL de SAP desde el primer procedimiento. Recuperarlo después, cuando ya hay decenas en uso, es arqueología.
• Pruebas contra una copia de la compañía. Los dos tropiezos del DocTotal se ven recién llamando a SAP. Una prueba que corra contra una base de respaldo los habría atrapado antes de producción.
• Una sola función de paginación en el gateway. El corte en 20 apareció en varias consultas a la vez porque cada una paginaba a su manera.
• La moneda explícita en cada monto. Ningún campo de dinero sin su moneda al lado, aunque parezca obvio.

Si estás por integrar con SAP Business One

Antes de escribir la primera consulta, decide quién es el único que habla con SAP. Si cada aplicación se conecta por su cuenta, después cuesta mucho juntar todo en un solo lugar. Y separa desde el inicio lo que se copia (los maestros) de lo que va en vivo: esa decisión define cuánto depende tu plataforma de que SAP esté disponible.

Si estás integrando con SAP Business One, escríbeme por LinkedIn. Me interesa saber cómo lo resolvieron otros equipos, sobre todo con el Service Layer.

Publicado originalmente en mi blog.

Cuando una empresa tiene dos o tres aplicaciones internas, cada una con sus propios botones y sus propias tablas, nadie lo nota. Cuando llega a quince, el usuario sí lo nota: cada pantalla filtra distinto, cada tabla exporta distinto y el modo oscuro funciona en unas y en otras no.

Hoy mantengo un Design System en Angular que usan 17 aplicaciones de una misma plataforma. Cuento cómo está armado, qué decisiones tomé al inicio y cuáles me tocó corregir en el camino.

Cómo está armado

Es un monorepo con Nx y ocho librerías, cada una con una responsabilidad:

 theme        tokens de diseño y temas claro/oscuro
 shared       tipos, utilidades y pipes (sin dependencias de UI)
 icons        un solo componente de íconos
 core         servicios base: notificaciones, diálogos, carga, errores HTTP
 ui           componentes presentacionales: botón, tarjeta, chip, alerta…
 forms        controles de formulario
 data-table   la tabla, con paginación, búsqueda, acciones y exportación
 charts       gráficos

Se publican como paquetes privados en GitHub Packages, y cada aplicación los instala como cualquier otra dependencia. Separarlas así hace que una aplicación que solo necesita formularios no cargue los gráficos, y que Nx sepa exactamente qué reconstruir cuando algo cambia.

Las aplicaciones nunca ven Angular Material

Los componentes están construidos sobre Angular Material, pero ninguna aplicación lo importa. Solo ven componentes propios, con un prefijo de la casa (aquí los muestro como ds-button, ds-data-table) y servicios propios que envuelven a los de Material: el de notificaciones envuelve al MatSnackBar, el de diálogos al MatDialog.

Lo decidí así por dos motivos. El primero es poder actualizar Material, o cambiarlo, sin tocar diecisiete aplicaciones. El segundo es que, si una aplicación puede usar Material directamente, tarde o temprano alguien arma su propio botón "porque era más rápido" y ahí empieza otra vez el desorden.

Esta regla no depende de que la gente se acuerde. La hace cumplir el linter, con la regla de límites de módulos de Nx:

'@nx/enforce-module-boundaries': ['error', {
  depConstraints: [
    {
      sourceTag: 'material:forbidden',
      bannedExternalImports: ['@angular/material', '@angular/material/*']
    }
  ]
}]

Si una librería que no debe importar Material lo importa, el lint falla y el paquete no se publica.

Tokens en dos niveles

Los colores viven en dos capas. Los primitivos son los valores de la marca (el rojo, los grises). Los semánticos son variables CSS con nombre de uso: --ds-color-surface, --ds-color-text, --ds-color-border. Los componentes solo usan los semánticos, nunca un hexadecimal.

Con eso, el modo oscuro es cambiar el juego de valores de esas variables. No se recompila nada y el cambio es inmediato:

:root {
  --ds-color-surface: #ffffff;
  --ds-color-text: #1f2937;
}
@media (prefers-color-scheme: dark) {
  :root:not(.ds-light) {
    --ds-color-surface: #1e1e24;
    --ds-color-text: #e5e7eb;
  }
}

Aprendí por las malas por qué la regla de "solo tokens" también aplica a las aplicaciones, no solo a las librerías. Un formulario público, de los que se abren desde el celular, tenía la tarjeta y los textos con colores fijos. Los controles del Design System sí seguían el modo oscuro del teléfono, la tarjeta no. Resultado: texto gris claro sobre fondo blanco, ilegible. En la laptop de desarrollo, en modo claro, se veía perfecto. Desde entonces toda página pública se revisa con el sistema en modo oscuro antes de darla por buena.

Una tabla igual en todas las aplicaciones

El componente que más valor dio fue la tabla. ds-data-table trae paginación, orden, búsqueda, selección, acciones por fila, exportación a Excel y los estados de carga y de lista vacía. Cada aplicación le pasa los datos y las columnas, y nada más.

Pero tener el componente no alcanzó. Al principio cada módulo armaba su página de listado a su manera: uno con el botón "Nuevo" arriba a la derecha, otro con los filtros en una barra lateral, otro con un buscador que pedía elegir el campo. Así que escribí el estándar de cómo es una página de listado: la tabla siempre es ds-data-table; crear y filtrar van en el mismo menú, a la derecha del título; y hay un solo buscador sobre la tabla, que busca en todos los campos a la vez. Y dejé un módulo como referencia para copiar.

Desde que eso quedó escrito, una pantalla nueva sale igual a las demás aunque la haga otra persona del equipo.

Lo que me tocó corregir

Un servicio global dentro de un microfrontend

Las 17 aplicaciones se montan dentro de un portal con microfrontends (lo conté en este artículo). El servicio de diálogos del Design System se registra en la raíz (providedIn: 'root') y abre los diálogos sin un inyector propio. Dentro del portal, la raíz es la del portal, no la del módulo.

Así que un diálogo que hacía una llamada HTTP usaba el cliente HTTP del portal, sin el interceptor del módulo que agrega el token. El backend respondía 401 y el usuario veía "Sesión expirada" con la sesión perfectamente activa. Corriendo el módulo solo, en su propio puerto, funcionaba bien, porque ahí la raíz sí es la del módulo.

La solución inmediata fue abrir esos diálogos con MatDialog y el viewContainerRef del componente, y volver a proveer su servicio en las rutas del módulo. La lección más general: en un Design System que se va a usar dentro de microfrontends, cualquier servicio en la raíz tiene que pensarse para correr en un inyector que no es el tuyo.

Publicar sin romper

Al principio las ocho librerías subían de versión juntas, aunque solo cambiara una. Era simple, pero cada corrección en la tabla obligaba a publicar las ocho y a actualizar las ocho en cada aplicación. Hoy cada librería lleva su propia versión. El cuidado está en las dependencias internas: si ui pide core ^0.5.0 y core pasa a 0.6.0, ese rango ya no la acepta, así que hay que subirlas juntas.

La otra trampa fue el lockfile. El repositorio se desarrollaba en Windows y el pipeline de publicación corre en Linux, y npm resuelve distinto algunas dependencias opcionales de Storybook según la plataforma. Un package-lock.json generado en Windows hacía fallar el npm ci del pipeline. Lo resolví usando npm install en ese paso y dejándolo escrito en la guía de publicación, con el motivo, para que nadie lo "arregle" volviendo a npm ci.

Lo que se construye "mientras tanto"

Más de una vez alguien necesitó un componente, no lo encontró en la versión instalada y lo armó dentro de su módulo. A veces el componente ya existía en el código del Design System, solo que todavía no estaba publicado. La regla quedó así: antes de crear un componente se revisa el repositorio del Design System, no solo lo que está instalado. Y si de verdad falta, se agrega al Design System, no al módulo.

Qué haría distinto si empezara hoy

• Pruebas desde la primera librería. Las librerías base arrancaron sin pruebas unitarias, y el pipeline tiene que dejar pasar ese caso. Agregar pruebas después, con 17 aplicaciones encima, cuesta mucho más.
• Automatizar la actualización en las aplicaciones. Publicar es un comando. Lo caro es subir la versión y reinstalar en cada aplicación, y eso debería hacerlo un script o un bot que abra los cambios en cada repositorio.
• El mismo Node en desarrollo y en el pipeline. La mitad de los problemas con el lockfile venían de desarrollar con una versión de Node y publicar con otra.
• El catálogo publicado desde el día uno. El Storybook ayuda mucho más cuando cualquiera lo puede abrir en el navegador sin clonar nada. Es el primer lugar donde alguien debería buscar antes de construir.

Si estás por armar uno

Empieza con pocas piezas: los tokens, el botón, los controles de formulario y la tabla. Con eso se cubre la mayor parte de las pantallas de una aplicación empresarial. Y escribe desde el principio las reglas de cómo se usa, porque el componente solo no alcanza para que todas las pantallas se parezcan.

Si mantienes un Design System para varios equipos, escríbeme por LinkedIn. Me interesa saber cómo resuelven la actualización en todas las aplicaciones.

Publicado originalmente en mi blog.

Durante años, desplegar a Google Cloud desde GitHub significó lo mismo en casi todos los equipos: crear una cuenta de servicio, descargar su llave en JSON y pegarla en los secretos del repositorio. Funciona, pero esa llave no vence, da acceso a la nube a quien la tenga y termina copiada en más lugares de los que uno recuerda.

Hoy despliego más de 20 repositorios a Cloud Run sin una sola llave guardada. Cuento cómo lo armé con Workload Identity Federation y lo que fui aprendiendo en el camino.

El problema con la llave en JSON

Una llave de cuenta de servicio es una contraseña que no expira. Si se filtra (un log que la imprime, un fork, un backup, una persona que se va del equipo con una copia), quien la tenga puede actuar como esa cuenta hasta que alguien se dé cuenta y la revoque.

Y con muchos repositorios el riesgo se multiplica: veinte repos con su propia llave son veinte copias que rotar, vigilar y recordar. En la práctica, nadie las rota.

Cómo funciona Workload Identity Federation

La idea es simple: en lugar de guardar una credencial, GitHub le demuestra a Google quién es en el momento del despliegue.

 GitHub Actions                 Google Cloud
 ┌────────────────┐   token     ┌──────────────────────────┐
 │ workflow del   │ ──OIDC────▶ │ Workload Identity Pool   │
 │ repositorio    │  (firmado   │ ¿es de mi organización?  │
 └────────────────┘  por GitHub)│ ¿es este repositorio?    │
                                └────────────┬─────────────┘
                                             │ credencial temporal
                                             ▼
                                ┌──────────────────────────┐
                                │ cuenta de servicio       │
                                │ (permisos mínimos)       │
                                └────────────┬─────────────┘
                                             ▼
                                         Cloud Run

Cada ejecución del workflow recibe de GitHub un token firmado que dice qué repositorio lo pidió, en qué rama y en qué workflow. Google valida esa firma, revisa las condiciones que le configuraste y entrega una credencial que dura una hora. No hay nada que guardar ni nada que rotar.

El paso a paso

1. El pool y el proveedor

El pool agrupa las identidades externas en las que confías. El proveedor le dice a Google cómo validar los tokens de GitHub y qué datos tomar de ellos:

gcloud iam workload-identity-pools create github \
  --location=global --display-name="GitHub"

gcloud iam workload-identity-pools providers create-oidc github-actions \
  --location=global --workload-identity-pool=github \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --attribute-condition="assertion.repository_owner == 'mi-organizacion'"

La condición es la línea más importante. Sin ella, cualquier repositorio de GitHub podría intentar presentarse ante tu pool. Con ella, solo entran los de tu organización.

2. Quién puede usar la cuenta de servicio

La cuenta de servicio es la que tiene los permisos para desplegar. Lo que se configura es qué repositorio puede actuar como ella:

gcloud iam service-accounts add-iam-policy-binding \
  deployer@mi-proyecto.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/NUMERO_DEL_PROYECTO/locations/global/workloadIdentityPools/github/attribute.repository/mi-organizacion/mi-repo"

A esa cuenta le doy solo lo que necesita para desplegar: lanzar el build, publicar en Cloud Run, leer la imagen y los secretos, y actuar como la cuenta con la que corre el servicio. Nada de roles de propietario o editor del proyecto. Uso una cuenta de servicio por repositorio, así cada módulo despliega solo lo suyo.

3. El workflow

name: deploy
on:
  workflow_dispatch:

permissions:
  contents: read
  id-token: write   # sin esto GitHub no entrega el token

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: produccion
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: projects/NUMERO_DEL_PROYECTO/locations/global/workloadIdentityPools/github/providers/github-actions
          service_account: deployer@mi-proyecto.iam.gserviceaccount.com
      - uses: google-github-actions/setup-gcloud@v2
      - run: gcloud run deploy mi-servicio --source . --region us-central1

Fíjate en lo que no aparece: ningún secrets.GCP_KEY. Los dos valores del paso de autenticación no son secretos, son identificadores. Si alguien los ve, no puede hacer nada con ellos desde fuera de tu organización.

Lo que aprendí con más de 20 repositorios

Un repositorio nuevo nace sin permiso

El permiso de usar la cuenta de servicio se da por repositorio. Así que el primer despliegue de un módulo nuevo falla con un 403 que dice algo como "Permission 'iam.serviceAccounts.getAccessToken' denied". No es un error del workflow: falta agregar ese repositorio a la lista.

Por eso el alta de cada módulo nuevo tiene tres pasos fijos: su cuenta de servicio, el permiso sobre el pool y el workflow. La alternativa es autorizar a toda la organización con attribute.repository_owner; es más cómodo, pero cualquier repositorio nuevo podría desplegar, y prefiero que eso sea una decisión explícita.

El otro 403 clásico llega en el primer despliegue: el workflow se autentica bien, pero un paso falla con PERMISSION_DENIED porque a la cuenta le falta un permiso concreto. A mí me faltó el de leer la imagen del registro de artefactos. El mensaje dice exactamente qué permiso falta, así que se resuelve rápido, pero conviene tener la lista completa de roles antes de replicar el esquema en veinte repositorios.

Un despliegue en verde no significa que el servicio funcione

Este me costó caro. gcloud run deploy intenta dejar el servicio público y, si la cuenta no tiene permiso para cambiar su política de acceso, lo reporta como una advertencia y termina en éxito igual. El build sale en verde, el workflow sale en verde, y el servicio responde 403 a todo el mundo. Un módulo que todavía nadie usaba pasó semanas así, con cuatro despliegues en verde, hasta que alguien intentó entrar.

Desde entonces, después de cada despliegue verifico que el servicio responda, no solo que el workflow haya terminado bien.

Nada a producción sin una aprobación

Los despliegues son manuales (workflow_dispatch), también los de pruebas. El de producción usa un environment de GitHub con revisores obligatorios y despliega una versión que ya pasó por pruebas, no lo último que haya en la rama. Alguien tiene que aprobarlo, y queda registrado quién lo hizo y cuándo. Además, cada ambiente es un proyecto de Google Cloud distinto con sus propias cuentas de servicio: la de pruebas no puede tocar producción aunque alguien se equivoque de workflow.

El pipeline tiene que ser la única puerta

Si alguien puede desplegar desde su computadora o desde la consola web, todo lo anterior se puede saltar. Los logs de auditoría de Google Cloud registran quién desplegó cada revisión y desde dónde, así que armé una alerta sobre esos logs: cuando alguien despliega por fuera del pipeline, el equipo recibe un aviso con quién fue, qué cambió y desde qué herramienta. La consola queda solo para emergencias, y cuando se usa, se sabe.

Qué haría distinto si empezara hoy

• Prohibir las llaves desde el primer día. La política de organización iam.disableServiceAccountKeyCreation impide crear llaves nuevas. Con eso, nadie vuelve a la llave en JSON "solo por esta vez".
• Una plantilla de workflow compartida. Con más de 20 repositorios, cada mejora al pipeline se repetía veinte veces. Un workflow reutilizable lo resuelve en un solo lugar.
• Verificar que el servicio responda, como paso del propio workflow. Que el pipeline falle si el servicio no contesta, en lugar de depender de que alguien lo revise.
• Escribir el despliegue para Linux desde el principio. Para arrancar rápido reutilicé los scripts de despliegue que ya existían, y eso me ató a runners de Windows. Moverlo después cuesta más que hacerlo bien al inicio.

Si estás por empezar

Si hoy tienes una llave en JSON en los secretos de tu repositorio, migrar a Workload Identity Federation toma una tarde: crear el pool, el proveedor, el permiso y cambiar un paso del workflow. Después borras la llave, y esa es la mejor parte.

Si ya lo hiciste o te trabaste en algún paso, escríbeme por LinkedIn. Me interesa saber cómo lo resolvieron otros equipos.

Publicado originalmente en mi blog.

Hace unos meses me tocó llevar una plataforma corporativa a una arquitectura de microfrontends: un portal que carga más de 15 módulos, cada uno con su propio repositorio, su propio equipo y su propio despliegue. Hoy esos módulos salen a producción por separado, sin coordinar ventanas de despliegue entre equipos.

No voy a explicar qué es un microfrontend, de eso ya hay bastante escrito. Quiero contar lo que no sale en los tutoriales, lo que solo aparece cuando el segundo, el quinto y el décimo módulo ya están en producción.

Primero: cuándo NO usar microfrontends

Empiezo por aquí porque es la pregunta que más me hacen y la respuesta honesta es "casi nunca al inicio".

Si estás en la columna de la derecha, un monolito bien modularizado te da el 80 % del beneficio con el 20 % del costo. Los microfrontends son, sobre todo, una decisión de organización. Pagan cuando el cuello de botella es la coordinación entre equipos, no la calidad del código.

La arquitectura, en una imagen

                    ┌──────────────────────────────┐
   usuario  ───────▶│  HOST (portal)               │
                    │  · login único (OIDC)        │
                    │  · menú según permisos       │
                    │  · lee el manifiesto         │
                    └──────────────┬───────────────┘
                                   │ carga en tiempo de ejecución
            ┌──────────────────────┼──────────────────────┐
            ▼                      ▼                      ▼
     remoteEntry.json       remoteEntry.json       remoteEntry.json
     ┌──────────────┐       ┌──────────────┐       ┌──────────────┐
     │  Ventas      │       │  Calidad     │       │  RRHH        │
     │  repo propio │       │  repo propio │       │  repo propio │
     │  deploy      │       │  deploy      │       │  deploy      │
     │  propio      │       │  propio      │       │  propio      │
     └──────────────┘       └──────────────┘       └──────────────┘

El stack es Angular con Native Federation (@angular-architects/native-federation). Es el sucesor de Module Federation para el builder moderno de Angular basado en esbuild: en lugar de depender de webpack, usa los estándares del navegador (módulos ES e import maps).

El host no conoce a los módulos en tiempo de compilación. Los descubre al arrancar, desde un manifiesto:

// federation.manifest.json (uno por ambiente)
{
  "ventas":  "https://ventas.ejemplo.com/remoteEntry.json",
  "calidad": "https://calidad.ejemplo.com/remoteEntry.json"
}

// main.ts del host
initFederation('federation.manifest.json')
  .then(() => import('./bootstrap'));

// rutas del host
{
  path: 'ventas',
  loadChildren: () =>
    loadRemoteModule({ remoteName: 'ventas', exposedModule: './Routes' })
      .then(m => m.routes)
}

Hasta aquí es lo que trae cualquier tutorial. Lo que sigue lo aprendí en producción.

Lo que rompe en producción (y cómo lo resolví)

1. Las rutas absolutas dentro de un módulo

Un módulo se desarrolla solo, en su propio puerto, donde /detalle/42 funciona perfecto. Embebido en el portal, ese módulo vive bajo /ventas, y /detalle/42 manda al usuario a una ruta que no existe.

La regla: dentro de un módulo, toda navegación es relativa. routerLink="detalle/42" y router.navigate(['detalle', id], { relativeTo: route }). Es una línea en la guía del equipo y una revisión en cada pull request, pero ahorra el bug más repetido de toda la plataforma.

2. El CORS de remoteEntry.json

El host pide el remoteEntry.json y los chunks de cada módulo desde otro dominio. Si el servidor del módulo no responde con Access-Control-Allow-Origin, el navegador bloquea la carga y el usuario ve una pantalla en blanco sin ningún error útil en la interfaz.

La regla: el CORS de los archivos estáticos del módulo es parte de la plantilla del proyecto, no algo que cada equipo descubre por su cuenta. Todo módulo nuevo nace con la configuración de su servidor web ya resuelta.

3. La caché que esconde la versión nueva

Despliegas, todo sale en verde, y el usuario sigue viendo la versión anterior. El culpable casi siempre es remoteEntry.json: es el único archivo cuyo nombre no cambia entre versiones, así que si el navegador o un CDN lo guarda, apunta a chunks viejos.

La regla: remoteEntry.json se sirve sin caché; los chunks, que llevan un hash en el nombre, se pueden cachear para siempre. Así cada despliegue llega al usuario en la siguiente carga, sin pedirle a nadie que borre su caché.

4. Un manifiesto por ambiente… y la vez que se mezclaron

Cada ambiente (pruebas y producción) tiene su propio manifiesto con las URLs de sus módulos. Una vez, una construcción manual horneó los valores por defecto y el portal de producción terminó cargando módulos de pruebas. El síntoma fue un error de CORS; la causa, un ambiente mezclado.

La regla: el pipeline valida, antes de construir, que todas las URLs correspondan al ambiente destino, y aborta si no. Desde entonces ese error ya no puede repetirse, porque el pipeline no lo deja pasar.

5. Una sola versión del Design System en todos los módulos

Los módulos comparten librerías: Angular, el router y el Design System propio que usan 17 aplicaciones. Native Federation las comparte como singleton, pero si un módulo trae otra versión del Design System, el portal muestra dos estilos distintos en la misma pantalla o, peor, componentes que se rompen al navegar entre módulos.

La regla: cada cambio en el Design System se publica como paquete versionado y se actualiza en todos los módulos a la vez, no solo en el que lo necesitaba. Y no basta con subir el rango en el package.json: si la imagen se construye con npm ci, manda el lockfile, así que hay que reinstalar y versionar el lock también.

6. Un módulo en el menú que todavía no existe

El portal arma su menú desde un catálogo de módulos. Registrar un módulo antes de que esté desplegado en todos los ambientes hace que el portal intente cargar un remoteEntry.json que no existe, y esa ruta queda rota.

La regla: cada entrada del catálogo tiene un indicador de disponibilidad. El módulo aparece en el menú con una página de "próximamente" hasta que su servicio existe donde corre el portal.

El login: uno solo, en el host

La decisión que más simplificó todo: solo el host autentica. El portal maneja el inicio de sesión con OIDC (Keycloak) y los módulos reciben el token ya resuelto. Ningún módulo define su propia autorización ni su propio login.

Eso tiene dos efectos. Para el usuario, un solo inicio de sesión para toda la plataforma. Para los equipos, un módulo nuevo no empieza escribiendo pantallas de login, sino pantallas de negocio. Los permisos viajan en el token y el menú se arma según ellos.

Si cada módulo resuelve la seguridad a su manera, tienes tantos modelos de seguridad como módulos. Centralizarla es la única forma de poder auditarla.

Qué haría distinto si empezara hoy

• El Design System antes que el segundo módulo. Cada componente que un equipo construye "mientras tanto" es un componente que después hay que migrar.
• Las barreras del pipeline desde el día uno. La validación de ambientes la agregué después de un incidente. Pudo estar desde el inicio.
• Automatizar la actualización del Design System. Actualizar una librería en más de 15 repositorios a mano no escala: es exactamente el tipo de tarea que debe hacer un script, no una persona.
• Una plantilla de módulo. CORS, rutas relativas, configuración de federación y pipeline listos al crear el repositorio. Cada regla de este artículo debería ser un archivo de la plantilla, no un párrafo de la guía.

Para cerrar

Los microfrontends funcionan cuando resuelven un problema de organización: equipos que necesitan avanzar sin esperarse. La parte técnica —federación, manifiestos, rutas— se resuelve en una semana. Lo difícil es todo lo demás: que cada regla quede escrita, que las que importan se conviertan en barreras automáticas y que cualquier persona del equipo pueda sostener la plataforma con lo que está documentado.

Si estás evaluando microfrontends para tu equipo o ya estás peleando con alguno de estos problemas, escríbeme por LinkedIn. Me interesa saber cómo lo están resolviendo otros.

Publicado originalmente en mi blog.