WU / DOCSMICROFRONTENDS UNIVERSAIS
PT
REFERÊNCIA DE APIS10 MIN DE LEITURA · MARKDOWN ↗

Referência de composição e permissões

Contratos de instâncias, principals, manifestos, facades e wrappers com parâmetros e diferenças de distribuição.

Veja versões, mudanças e requisitos em Framework 4.0 e CLI 1.2.

Esta referência reúne as APIs com as quais o host configura identidade e autoridade. Os exemplos usam wu importado de wu-framework; um objeto chamado manifests é criado com new WuManifest().

Distribuição e receptor

O singleton é a autoridade do host. A facade context.wu é recebida a partir do lifecycle e concede apenas a interseção entre as solicitações do manifesto e os grants do host. Os papéis do principal controlam o acesso à interface; a autorização dos dados do servidor é verificada no servidor.

Preparar um wrapper sobre uma 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();

O destino deve existir no documento. As fichas do wrapper descrevem seus métodos de runtime; a declaração TypeScript de WuApp enumera apenas uma parte. Criar outro wrapper não substitui os grants de um registro existente.

wu.app

Cria um objeto reutilizável que mantém a identidade e a configuração de uma microapp.

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

  • name e config.url; container aceita um seletor string ou, desde a versão 3.2, um HTMLElement. Os outros campos pertencem ao host.
  • Retorno: WuApp com registro adiado até mount().
  • Erros: A montagem propaga falhas de manifest, permissões, carga e contêiner.
  • Permissões: O wrapper preserva configuração e grants do host e registra pelo core.
  • Limpeza: unmount remove o renderer; destroy do wrapper não limpa todos os registros de manifesto.
const catalog = wu.app('catalog', {
  url: '/apps/catalog', container: '#catalog-slot',
});
console.log(catalog.info);

Referência: src/index.js.

new WuCore

Cria uma instância com store próprio ou um injetado deliberadamente.

new WuCore(options?): WuCore

  • Parâmetros: store, storeBufferSize e compatibility são opcionais.
  • Retorno: Instância independente; o import wu continua sendo o singleton.
  • Erros: Não inicia apps; erros de opções/compatibility são propagados.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: await runtime.destroy() ao remover a instância.
import { WuCore, WuStore } from 'wu-framework';
const runtime = new WuCore({ store: new WuStore(512) });

Referência: src/core/wu-core.js.

wu.setPrincipal

Define o principal usado pelo controle de acesso à montagem.

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

  • Parâmetros: role, roles e permissions como mount:catalog ou mount:*; null encerra a identidade.
  • Retorno: O mesmo principal ou null; projeta auth.principal e informa a mudança.
  • Erros: Uma gravação malsucedida no store não reverte o principal.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: wu.setPrincipal(null) quando a sessão terminar.
wu.setPrincipal({ roles: ['catalog-reader'] });

Referência: src/core/wu-core.js.

wu.getPrincipal

Lê o principal atual usado pelo host.

wu.getPrincipal(): object | null

  • Parâmetros: Sem argumentos.
  • Retorno: Referência do principal, ou null.
  • Erros: Não valida a sessão nem consulta o servidor.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
console.log(wu.getPrincipal()?.roles);

Referência: src/core/wu-core.js.

wu.can

Verifica se o principal atende aos papéis de uma aplicação.

wu.can(appName: string): boolean

  • Parâmetros: Nome registrado; consulta os papéis normalizados do manifesto.
  • Retorno: Booleano; apps sem papéis são consideradas públicas.
  • Erros: Não verifica a existência da entrada nem concede capabilities do store/barramento.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
if (wu.can('catalog')) await wu.mount('catalog', '#catalog-slot');

Referência: src/core/wu-core.js.

context.wu

Fornece a cada lifecycle uma autoridade revogável de aplicação.

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

  • Parâmetros: O core fornece context; uma facade não é construída a partir de um nome.
  • Retorno: Facade congelada com eventos, RPC, contratos e store limitado.
  • Erros: WU_APP_SCOPE_REVOKED após teardown; WU_CAPABILITY_DENIED ao acessar recursos sem grant.
  • Permissões: Interseção entre manifest.wu.permissions e config.grants; não expõe init, destroy nem administração global.
  • Limpeza: Libere o trabalho próprio em unmount; não reutilize a facade depois.
wu.define('catalog', {
  mount(container, { wu: appWu }) {
    container.textContent = String(appWu.store.get('catalog.count') ?? 0);
  },
});

Referência: src/core/wu-core.js.

new WuManifest

Cria um leitor e validador de manifestos com cache próprio.

new WuManifest(): WuManifest

  • Parâmetros: Sem argumentos obrigatórios.
  • Retorno: Instância para load, validate, create e clearCache.
  • Erros: Não concede permissões nem registra apps em um core.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: clearCache() descarta os manifestos em cache.
import { WuManifest } from 'wu-framework';
const manifests = new WuManifest();

Referência: src/core/wu-manifest.js.

WuManifest.load

Baixa e normaliza wu.json a partir da URL base de uma app.

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

  • Parâmetros: appUrl: base pública; expectedName vincula a identidade do registro.
  • Retorno: Manifesto normalizado; um 404 real usa o manifesto padrão.
  • Erros: WU_MANIFEST_LOAD_FAILED, WU_MANIFEST_INVALID e WU_MANIFEST_NAME_MISMATCH; rede/HTML/500 não são padrões.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: clearCache(base) quando precisar descartar a leitura.
const manifest = await manifests.load('/apps/catalog', { expectedName: 'catalog' });

Referência: src/core/wu-manifest.js.

WuManifest.validate

Valida estrutura, limites, caminhos e permissões declarativas sem concedê-las.

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

  • Parâmetros: Objeto de dados próprio; resource é obrigatório em declarações de objeto.
  • Retorno: Manifesto normalizado com snapshots congelados.
  • Erros: WU_MANIFEST_INVALID ou identidade diferente de expectedName.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
const manifest = manifests.validate({ name: 'catalog', entry: 'entry.js', wu: { permissions: [] } });

Referência: src/core/wu-manifest.js.

WuManifest.create

Produz um manifesto a partir de uma identidade e uma configuração declarativa.

manifests.create(name, config?): object

  • Parâmetros: name; config.entry (index.js por padrão), exports, imports, permissions, roles, metadata, styleMode, version e folder. routes não vazias não são válidas em wu.routes.
  • Retorno: Manifesto construído e validado.
  • Erros: As mesmas restrições estruturais de validate.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
const manifest = manifests.create('catalog', { entry: 'entry.js' });

Referência: src/core/wu-manifest.js.

WuManifest.clearCache

Descarta os manifestos armazenados para baixá-los novamente.

manifests.clearCache(pattern?): void

  • Parâmetros: Expressão regular em string; sem padrão, remove todo o cache desta instância.
  • Retorno: void.
  • Erros: Um padrão RegExp inválido emite um aviso e não remove entradas; não altera os registros compilados do core.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
manifests.clearCache('/apps/catalog');

Referência: src/core/wu-manifest.js.

wu.compatibility.configure

Configura pontes limitadas de migração entre os perfis strict e compat-v2.

wu.compatibility.configure(config): WuCompatibility

  • Parâmetros: profile, warnings e opções ai/plugins/apps/sync; não é um sandbox adicional.
  • Retorno: A mesma instância.
  • Erros: Configuração ou feature desconhecida pode lançar um erro.
  • Permissões: Apenas host; cada ponte deve ser habilitada explicitamente.
  • Limpeza: Não cria recursos que precisem ser liberados.
wu.compatibility.configure({ profile: 'strict', warnings: 'once' });

Referência: src/core/wu-compatibility.js.

wu.compatibility.getConfig

Consulta o perfil efetivo e suas pontes de migração.

wu.compatibility.getConfig(): object

  • Parâmetros: Sem argumentos.
  • Retorno: Configuração de compatibilidade.
  • Erros: Não comprova que um consumidor esteja usando uma ponte.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
console.log(wu.compatibility.getConfig());

Referência: src/core/wu-compatibility.js.

wu.compatibility.getMigrationReport

Lê avisos acumulados de uso de compatibilidade.

wu.compatibility.getMigrationReport(): object[]

  • Parâmetros: Sem argumentos.
  • Retorno: Entradas com código, mensagem, contagem e tempos.
  • Erros: Registra apenas usos instrumentados; não é uma análise estática das suas apps.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
console.table(wu.compatibility.getMigrationReport());

Referência: src/core/wu-compatibility.js.

wu.compatibility.clearMigrationReport

Reinicia o registro de avisos de migração.

wu.compatibility.clearMigrationReport(): void

  • Parâmetros: Sem argumentos.
  • Retorno: void.
  • Erros: Não altera as opções de compatibilidade.
  • Permissões: Host; não está disponível na facade da aplicação.
  • Limpeza: Não cria recursos que precisem ser liberados.
wu.compatibility.clearMigrationReport();

Referência: src/core/wu-compatibility.js.

WuApp.mount

Monta a identidade do wrapper e guarda o seletor.

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

  • Parâmetros: Seletor opcional; usa config.container quando ausente.
  • Retorno: Promise
  • Erros: Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar.
  • Permissões: Autoridade do core proprietário do wrapper.
  • Limpeza: Equilibre com widget.unmount().
await widget.mount('#widget-slot');

Referência: src/core/wu-app.js.

WuApp.unmount

Libera a referência do wrapper ou mantém keep-alive.

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

  • Parâmetros: force remove completamente; keepAlive mantém o DOM.
  • Retorno: Promise
  • Erros: Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar.
  • Permissões: Autoridade do core proprietário do wrapper.
  • Limpeza: Chama o unmount do renderizador quando necessário.
await widget.unmount({ force: true });

Referência: src/core/wu-app.js.

WuApp.hide

Oculta uma instância mantida pelo wrapper.

widget.hide(): Promise<WuApp>

  • Parâmetros: Sem argumentos; requer uma instância montada.
  • Retorno: Promise
  • Erros: Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar.
  • Permissões: Autoridade do core proprietário do wrapper.
  • Limpeza: deactivate deve pausar os timers próprios.
await widget.hide();

Referência: src/core/wu-app.js.

WuApp.show

Reativa a instância keep-alive do wrapper.

widget.show(): Promise<WuApp>

  • Parâmetros: Sem argumentos; requer estado oculto.
  • Retorno: Promise
  • Erros: Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar.
  • Permissões: Autoridade do core proprietário do wrapper.
  • Limpeza: Finalize depois com unmount.
await widget.show();

Referência: src/core/wu-app.js.

WuApp.remount

Força a desmontagem e monta novamente no destino escolhido.

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

  • Parâmetros: Seletor opcional; mantém o último destino.
  • Retorno: Promise
  • Erros: Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar.
  • Permissões: Autoridade do core proprietário do wrapper.
  • Limpeza: Destrói o renderizador anterior.
await widget.remount('#widget-slot');

Referência: src/core/wu-app.js.

WuApp.reload

Limpa os caches disponíveis de loader/manifesto e monta novamente.

widget.reload(): Promise<WuApp>

  • Parâmetros: Sem argumentos; usa o destino guardado.
  • Retorno: Promise
  • Erros: Propaga falhas de registro/montagem; métodos de visibilidade ausentes emitem avisos sem montar.
  • Permissões: Autoridade do core proprietário do wrapper.
  • Limpeza: Não invalida o cache nativo de import ESM do navegador.
await widget.reload();

Referência: src/core/wu-app.js.

WuApp.verify

Inspeciona registro, montagem e ShadowRoot do slot.

widget.verify(): Promise<object>