perfil/PWA_SCOPE_EXTENSIONS.md

Configuración de Scope Extensions y Link Handling en Nucleo V3

Resumen

Este documento describe la implementación de Scope Extensions y Link Handling en las PWAs del ecosistema Nucleo V3, permitiendo que múltiples aplicaciones web en diferentes subdominios funcionen como un sistema unificado de aplicaciones progresivas.

¿Qué son Scope Extensions?

Scope Extensions es una característica de las Progressive Web Apps que permite a una PWA extender su scope (alcance) a otros orígenes (dominios/subdominios). Esto significa que:

• Una PWA instalada puede "capturar" navegaciones a otros subdominios
• Los usuarios pueden moverse entre apps manteniendo la experiencia de PWA
• El ecosistema de apps se siente más integrado y cohesivo

Arquitectura Implementada

Hub Principal: Perfil PWA

La aplicación perfil (inicio.nucleoriofrio.com) actúa como el hub principal del ecosistema Nucleo V3, con la capacidad de capturar navegaciones a:

• musica.nucleoriofrio.com (RepoDructor)
• docs.nucleoriofrio.com (Nucleo Docs)
• analitica.nucleoriofrio.com (Analítica Nucleo)
• seguidordelotes.nucleoriofrio.com (Seguidor de Lotes)
• whisper.nucleoriofrio.com (Nucleo Whisper)
• amigos.nucleoriofrio.com (Amigos App)

Apps Secundarias

Cada app secundaria puede:

• Funcionar de manera independiente como PWA
• Confirmar su asociación con la PWA de Perfil mediante archivos .well-known
• Capturar enlaces dentro de su propio scope

Componentes de la Implementación

1. Manifests (nuxt.config.ts)

Perfil (Hub Principal)

manifest: {
  // ... otras propiedades ...
  capture_links: 'existing-client-navigate',
  scope_extensions: [
    { origin: "https://musica.nucleoriofrio.com" },
    { origin: "https://docs.nucleoriofrio.com" },
    { origin: "https://analitica.nucleoriofrio.com" },
    { origin: "https://seguidordelotes.nucleoriofrio.com" },
    { origin: "https://whisper.nucleoriofrio.com" },
    { origin: "https://amigos.nucleoriofrio.com" }
  ]
}

Apps Secundarias

manifest: {
  // ... otras propiedades ...
  capture_links: 'existing-client-navigate'
}

2. Archivos .well-known/web-app-origin-association

Cada app secundaria debe tener este archivo en public/.well-known/web-app-origin-association:

{
  "web_apps": [
    {
      "manifest": "https://inicio.nucleoriofrio.com/manifest.webmanifest",
      "details": {
        "paths": ["/*"]
      }
    }
  ]
}

Ubicaciones:

• /home/draganel/repos/repodructor/public/.well-known/web-app-origin-association
• /home/draganel/repos/nucleoDocs/nuxt4/public/.well-known/web-app-origin-association
• /home/draganel/repos/nucleoWhisper/nuxt4/public/.well-known/web-app-origin-association
• /home/draganel/repos/analiticaNucleo/nuxt4-app/public/.well-known/web-app-origin-association
• /home/draganel/repos/seguidorDeLotes/nuxt4-app/public/.well-known/web-app-origin-association

3. Configuración de Traefik (docker-compose.yml)

Cada docker-compose.yml ha sido actualizado para servir los archivos .well-known sin autenticación, con alta prioridad:

# Router público para recursos PWA (sin autenticación)
- "traefik.http.routers.${APP_NAME}-public.rule=Host(`${APP_DOMAIN}`) && (PathPrefix(`/.well-known`) || PathPrefix(`/manifest.webmanifest`) || ...)"
- "traefik.http.routers.${APP_NAME}-public.priority=100"

Flujo de Usuario

1. Instalación de Perfil PWA

   • Usuario instala la PWA de Perfil desde inicio.nucleoriofrio.com
   • El navegador lee el manifest y detecta los scope_extensions
   • El navegador valida automáticamente los archivos .well-known en cada origen extendido

2. Navegación entre Apps

   • Usuario hace clic en un enlace a musica.nucleoriofrio.com desde cualquier app
   • Si la PWA de Perfil está instalada y configurada correctamente:
     • El navegador puede abrir el enlace dentro de la ventana de la PWA
     • En lugar de abrir el navegador normal
   • La experiencia es más fluida y cohesiva

3. Apps Independientes

   • Cada app puede seguir siendo instalada independientemente
   • Cada app mantiene su propio Service Worker y caché
   • Las apps pueden funcionar offline según su configuración individual

Limitaciones Técnicas

Same-Origin Policy

Aunque las apps comparten el link handling, NO comparten:

• Service Workers (cada origen tiene el suyo)
• Caches (cada origen tiene su propio cache storage)
• Almacenamiento local (localStorage, IndexedDB)
• Permisos (cada origen pide permisos independientemente)

Soporte de Navegadores

• Chromium-based browsers (Chrome, Edge): Soporte completo
• Firefox: Soporte limitado o experimental
• Safari: Sin soporte actualmente

Validación y Testing

Verificar Implementación

1. Verificar archivos .well-known:

# Debe devolver el JSON de asociación
curl https://musica.nucleoriofrio.com/.well-known/web-app-origin-association

2. Verificar manifest de Perfil:

# Debe contener scope_extensions
curl https://inicio.nucleoriofrio.com/manifest.webmanifest | grep scope_extensions

3. Instalar y probar:
   • Instalar la PWA de Perfil en Chrome/Edge
   • Hacer clic en enlaces a otras apps del ecosistema
   • Verificar que se abren dentro de la ventana de la PWA

Debugging

Chrome DevTools:

1. Abrir DevTools → Application → Manifest
2. Verificar que scope_extensions aparece correctamente
3. En la consola, verificar errores relacionados con .well-known

Edge DevTools: Similar a Chrome, con soporte adicional para PWA features

Mantenimiento

Agregar una Nueva App al Ecosistema

1. Actualizar el manifest de Perfil (/home/draganel/repos/perfil/nuxt4/nuxt.config.ts):

scope_extensions: [
  // ... extensiones existentes ...
  {
    origin: "https://nuevaapp.nucleoriofrio.com"
  }
]

2. Crear .well-known en la nueva app:

mkdir -p /ruta/a/nuevaapp/public/.well-known

Crear /ruta/a/nuevaapp/public/.well-known/web-app-origin-association:

{
  "web_apps": [
    {
      "manifest": "https://inicio.nucleoriofrio.com/manifest.webmanifest",
      "details": {
        "paths": ["/*"]
      }
    }
  ]
}

3. Actualizar docker-compose.yml de la nueva app:

- "traefik.http.routers.nuevaapp-public.rule=Host(`nuevaapp.nucleoriofrio.com`) && (PathPrefix(`/.well-known`) || ...)"

4. Agregar capture_links al manifest de la nueva app:

manifest: {
  // ... otras propiedades ...
  capture_links: 'existing-client-navigate'
}

Remover una App del Ecosistema

1. Remover el origen de scope_extensions en el manifest de Perfil
2. Eliminar el archivo .well-known de la app
3. Rebuild y redeploy ambas apps

Archivos Modificados

Manifests Actualizados

• ✅ /home/draganel/repos/perfil/nuxt4/nuxt.config.ts
• ✅ /home/draganel/repos/repodructor/nuxt.config.ts
• ✅ /home/draganel/repos/nucleoDocs/nuxt4/nuxt.config.ts
• ✅ /home/draganel/repos/nucleoWhisper/nuxt4/nuxt.config.ts
• ✅ /home/draganel/repos/analiticaNucleo/nuxt4-app/nuxt.config.ts
• ✅ /home/draganel/repos/seguidorDeLotes/nuxt4-app/nuxt.config.ts

Archivos .well-known Creados

• ✅ /home/draganel/repos/repodructor/public/.well-known/web-app-origin-association
• ✅ /home/draganel/repos/nucleoDocs/nuxt4/public/.well-known/web-app-origin-association
• ✅ /home/draganel/repos/nucleoWhisper/nuxt4/public/.well-known/web-app-origin-association
• ✅ /home/draganel/repos/analiticaNucleo/nuxt4-app/public/.well-known/web-app-origin-association
• ✅ /home/draganel/repos/seguidorDeLotes/nuxt4-app/public/.well-known/web-app-origin-association

Docker Compose Actualizados

• ✅ /home/draganel/repos/perfil/docker-compose.yml
• ✅ /home/draganel/repos/repodructor/docker-compose.yml
• ✅ /home/draganel/repos/nucleoDocs/docker-compose.yml
• ✅ /home/draganel/repos/nucleoWhisper/docker-compose.yml
• ✅ /home/draganel/repos/analiticaNucleo/docker-compose.yml
• ✅ /home/draganel/repos/seguidorDeLotes/docker-compose.yml

Referencias

• Building multiple Progressive Web Apps on the same domain - Google
• Handle links to a PWA - Microsoft Edge Developer
• Scope Extensions for Web App Manifest - W3C

Soporte

Para problemas o preguntas sobre esta configuración, contactar a:

• Desarrollador: Dario (Leouch, Draganel, nucleo000)
• Empresa: Nucleo Rio Frio

---

Fecha de implementación: 2025-10-17 Versión: 1.0 Sistema: Nucleo V3