WU / DOCSUNIVERSAL MICROFRONTENDS
ES
REFERENCIA DE APIS10 MIN DE LECTURA · MARKDOWN ↗

Referencia de composición y permisos

Contratos de instancias, principals, manifests, facades y wrappers con parámetros y diferencias de distribución.

Consulta las versiones, cambios y requisitos en Framework 4.0 y CLI 1.2.

Esta referencia reúne las APIs con las que el host configura identidad y autoridad. Los ejemplos usan wu importado desde wu-framework; un objeto llamado manifests se crea con new WuManifest().

Distribución y receptor

El singleton es autoridad de host. La facade context.wu se recibe desde el lifecycle y concede solo la intersección de solicitudes del manifest y grants del host. Los roles del principal controlan acceso de interfaz; la autorización de datos del servidor se verifica en el servidor.

Preparar un wrapper sobre una app registrada

import { wu, WuManifest } from 'wu-framework';

const manifests = new WuManifest();
await wu.init({ apps: [{ name: 'widget', url: '/apps/widget' }] });
const widget = wu.app('widget', {
  url: '/apps/widget', container: '#widget-slot',
});
await widget.mount();

El destino debe existir en el documento. Las fichas del wrapper describen sus métodos de runtime; la declaración TypeScript de WuApp solo enumera una parte. Crear otro wrapper no sustituye los grants de un registro existente.

wu.app

Crea un objeto reutilizable que conserva la identidad y configuración de una microapp.

wu.app(name: string, config: Partial<WuAppConfig>): WuApp

  • Parámetros: name y config.url; container acepta un selector string o, desde 3.2, un HTMLElement. Los demás campos pertenecen al host.
  • Retorno: WuApp con registro diferido hasta mount().
  • Errores: El montaje propaga fallos del manifest, permisos, carga y contenedor.
  • Permisos: El wrapper conserva configuración y grants del host y registra mediante el core.
  • Limpieza: unmount retira renderer; destroy del wrapper no limpia todos los registros de manifest.
const catalog = wu.app('catalog', {
  url: '/apps/catalog', container: '#catalog-slot',
});
console.log(catalog.info);

Referencia: src/index.js.

new WuCore

Crea una instancia con store propio o uno inyectado de forma deliberada.

new WuCore(options?): WuCore

  • Parámetros: store, storeBufferSize y compatibility son opcionales.
  • Retorno: Instancia independiente; el import wu continúa siendo el singleton.
  • Errores: No inicia apps; errores de opciones/compatibility se propagan.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: await runtime.destroy() al retirar la instancia.
import { WuCore, WuStore } from 'wu-framework';
const runtime = new WuCore({ store: new WuStore(512) });

Referencia: src/core/wu-core.js.

wu.setPrincipal

Establece el principal usado por el control de acceso al montaje.

wu.setPrincipal(principal | null): object | null

  • Parámetros: role, roles y permissions como mount:catalog o mount:*; null cierra la identidad.
  • Retorno: El mismo principal o null; proyecta auth.principal e informa el cambio.
  • Errores: Una escritura fallida en el store no revierte el principal.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: wu.setPrincipal(null) cuando termine la sesión.
wu.setPrincipal({ roles: ['catalog-reader'] });

Referencia: src/core/wu-core.js.

wu.getPrincipal

Lee el principal actual que utiliza el host.

wu.getPrincipal(): object | null

  • Parámetros: Sin argumentos.
  • Retorno: Referencia del principal, o null.
  • Errores: No valida sesión ni consulta al servidor.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
console.log(wu.getPrincipal()?.roles);

Referencia: src/core/wu-core.js.

wu.can

Comprueba si el principal satisface los roles de una aplicación.

wu.can(appName: string): boolean

  • Parámetros: Nombre registrado; consulta roles normalizados del manifest.
  • Retorno: Booleano; apps sin roles se consideran públicas.
  • Errores: No comprueba existencia del entry ni concede capabilities del store/bus.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
if (wu.can('catalog')) await wu.mount('catalog', '#catalog-slot');

Referencia: src/core/wu-core.js.

context.wu

Entrega a cada lifecycle una autoridad revocable de aplicación.

mount(container, context: { appName, wu: WuAppFacade }): void | Promise<void>

  • Parámetros: El core entrega context; no se construye una facade a partir de un nombre.
  • Retorno: Facade congelada con eventos, RPC, contratos y store limitado.
  • Errores: WU_APP_SCOPE_REVOKED tras teardown; WU_CAPABILITY_DENIED al acceder a recursos sin grant.
  • Permisos: Intersección manifest.wu.permissions y config.grants; no expone init, destroy ni administración global.
  • Limpieza: Libera trabajo propio en unmount; no reutilices la facade después.
wu.define('catalog', {
  mount(container, { wu: appWu }) {
    container.textContent = String(appWu.store.get('catalog.count') ?? 0);
  },
});

Referencia: src/core/wu-core.js.

new WuManifest

Crea un lector y validador de manifests con caché propia.

new WuManifest(): WuManifest

  • Parámetros: Sin argumentos requeridos.
  • Retorno: Instancia para load, validate, create y clearCache.
  • Errores: No otorga permisos ni registra apps en un core.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: clearCache() descarta manifests cacheados.
import { WuManifest } from 'wu-framework';
const manifests = new WuManifest();

Referencia: src/core/wu-manifest.js.

WuManifest.load

Descarga y normaliza wu.json desde la URL base de una app.

manifests.load(appUrl, { expectedName? }?): Promise<object>

  • Parámetros: appUrl: base pública; expectedName vincula la identidad del registro.
  • Retorno: Manifest normalizado; un 404 real usa el manifest por defecto.
  • Errores: WU_MANIFEST_LOAD_FAILED, WU_MANIFEST_INVALID y WU_MANIFEST_NAME_MISMATCH; red/HTML/500 no son defaults.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: clearCache(base) cuando necesites descartar la lectura.
const manifest = await manifests.load('/apps/catalog', { expectedName: 'catalog' });

Referencia: src/core/wu-manifest.js.

WuManifest.validate

Valida estructura, límites, rutas y permisos declarativos sin concederlos.

manifests.validate(manifest, { expectedName? }?): object

  • Parámetros: Objeto de datos propio; resource es obligatorio en declaraciones objeto.
  • Retorno: Manifest normalizado con snapshots congelados.
  • Errores: WU_MANIFEST_INVALID o identidad distinta de expectedName.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
const manifest = manifests.validate({ name: 'catalog', entry: 'entry.js', wu: { permissions: [] } });

Referencia: src/core/wu-manifest.js.

WuManifest.create

Produce un manifest desde una identidad y configuración declarativa.

manifests.create(name, config?): object

  • Parámetros: name; config.entry (index.js por defecto), exports, imports, permissions, roles, metadata, styleMode, version y folder. routes no vacías no son válidas en wu.routes.
  • Retorno: Manifest construido y validado.
  • Errores: Las mismas restricciones estructurales de validate.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
const manifest = manifests.create('catalog', { entry: 'entry.js' });

Referencia: src/core/wu-manifest.js.

WuManifest.clearCache

Descarta manifests almacenados para volver a descargarlos.

manifests.clearCache(pattern?): void

  • Parámetros: Expresión regular en string; sin patrón elimina toda la caché de esta instancia.
  • Retorno: void.
  • Errores: Un patrón RegExp inválido advierte y no elimina entradas; no altera registros compilados del core.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
manifests.clearCache('/apps/catalog');

Referencia: src/core/wu-manifest.js.

wu.compatibility.configure

Configura puentes acotados de migración entre perfiles strict y compat-v2.

wu.compatibility.configure(config): WuCompatibility

  • Parámetros: profile, warnings y opciones ai/plugins/apps/sync; no es un sandbox adicional.
  • Retorno: La misma instancia.
  • Errores: Configuración o feature desconocida puede lanzar.
  • Permisos: Solo host; cada puente debe habilitarse explícitamente.
  • Limpieza: No crea recursos que deban liberarse.
wu.compatibility.configure({ profile: 'strict', warnings: 'once' });

Referencia: src/core/wu-compatibility.js.

wu.compatibility.getConfig

Consulta el perfil efectivo y sus puentes de migración.

wu.compatibility.getConfig(): object

  • Parámetros: Sin argumentos.
  • Retorno: Configuración de compatibilidad.
  • Errores: No demuestra que un consumidor esté usando un puente.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
console.log(wu.compatibility.getConfig());

Referencia: src/core/wu-compatibility.js.

wu.compatibility.getMigrationReport

Lee advertencias acumuladas de uso de compatibilidad.

wu.compatibility.getMigrationReport(): object[]

  • Parámetros: Sin argumentos.
  • Retorno: Entradas con código, mensaje, conteo y tiempos.
  • Errores: Solo registra usos instrumentados; no es un análisis estático de tus apps.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
console.table(wu.compatibility.getMigrationReport());

Referencia: src/core/wu-compatibility.js.

wu.compatibility.clearMigrationReport

Reinicia el registro de advertencias de migración.

wu.compatibility.clearMigrationReport(): void

  • Parámetros: Sin argumentos.
  • Retorno: void.
  • Errores: No cambia las opciones de compatibilidad.
  • Permisos: Host; no está disponible en la facade de aplicación.
  • Limpieza: No crea recursos que deban liberarse.
wu.compatibility.clearMigrationReport();

Referencia: src/core/wu-compatibility.js.

WuApp.mount

Monta la identidad del wrapper y recuerda el selector.

widget.mount(target?: string | HTMLElement): Promise<WuApp>

  • Parámetros: Selector opcional; utiliza config.container cuando falta.
  • Retorno: Promise
  • Errores: Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar.
  • Permisos: Autoridad del core propietario del wrapper.
  • Limpieza: Equilibra con widget.unmount().
await widget.mount('#widget-slot');

Referencia: src/core/wu-app.js.

WuApp.unmount

Libera la referencia del wrapper o conserva keep-alive.

widget.unmount(options?: { force?: boolean; keepAlive?: boolean }): Promise<WuApp>

  • Parámetros: force retira completamente; keepAlive conserva DOM.
  • Retorno: Promise
  • Errores: Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar.
  • Permisos: Autoridad del core propietario del wrapper.
  • Limpieza: Llama al unmount del renderer cuando corresponde.
await widget.unmount({ force: true });

Referencia: src/core/wu-app.js.

WuApp.hide

Oculta una instancia conservada por el wrapper.

widget.hide(): Promise<WuApp>

  • Parámetros: Sin argumentos; requiere una instancia montada.
  • Retorno: Promise
  • Errores: Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar.
  • Permisos: Autoridad del core propietario del wrapper.
  • Limpieza: deactivate debe pausar timers propios.
await widget.hide();

Referencia: src/core/wu-app.js.

WuApp.show

Reactiva la instancia keep-alive del wrapper.

widget.show(): Promise<WuApp>

  • Parámetros: Sin argumentos; requiere estado oculto.
  • Retorno: Promise
  • Errores: Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar.
  • Permisos: Autoridad del core propietario del wrapper.
  • Limpieza: Finaliza después con unmount.
await widget.show();

Referencia: src/core/wu-app.js.

WuApp.remount

Fuerza desmontaje y monta otra vez sobre el destino elegido.

widget.remount(target?: string | HTMLElement): Promise<WuApp>

  • Parámetros: Selector opcional; conserva el último destino.
  • Retorno: Promise
  • Errores: Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar.
  • Permisos: Autoridad del core propietario del wrapper.
  • Limpieza: Destruye el renderer anterior.
await widget.remount('#widget-slot');

Referencia: src/core/wu-app.js.

WuApp.reload

Limpia las cachés de loader/manifest disponibles y vuelve a montar.

widget.reload(): Promise<WuApp>

  • Parámetros: Sin argumentos; utiliza el destino recordado.
  • Retorno: Promise
  • Errores: Propaga fallos de registro/montaje; métodos de visibilidad ausentes advierten sin montar.
  • Permisos: Autoridad del core propietario del wrapper.
  • Limpieza: No invalida el caché nativo de import ESM del navegador.
await widget.reload();

Referencia: src/core/wu-app.js.

WuApp.verify

Inspecciona registro, montaje y ShadowRoot del slot.

widget.verify(): Promise<object>