WU / DOCSUNIVERSAL MICROFRONTENDS
EN
API REFERENCE10 MIN READ · MARKDOWN ↗

Composition and permission reference

Contracts for instances, principals, manifests, facades, and wrappers, with parameters and distribution differences.

See versions, changes and requirements in Framework 4.0 and CLI 1.2.

This reference gathers the APIs the host uses to configure identity and authority. Examples use wu imported from wu-framework; an object named manifests is created with new WuManifest().

Distribution and receiver

The singleton has host authority. The context.wu facade is received through lifecycle and grants only the intersection of manifest requests and host grants. Principal roles control interface access; server data authorization is checked on the server.

Preparing a wrapper around a registered app

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();

The target must exist in the document. Wrapper entries describe its runtime methods; the WuApp TypeScript declaration lists only some. Creating another wrapper does not replace an existing registration’s grants.

wu.app

Creates a reusable object preserving a microapp’s identity and configuration.

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

  • name and config.url; container accepts a string selector or, since 3.2, an HTMLElement. Other fields belong to the host.
  • Returns: WuApp with registration deferred until mount().
  • Errors: Mounting propagates manifest, permission, loading and container failures.
  • Permissions: The wrapper preserves host configuration and grants and registers through the core.
  • Cleanup: unmount removes the renderer; wrapper destroy does not clear every manifest registration.
const catalog = wu.app('catalog', {
  url: '/apps/catalog', container: '#catalog-slot',
});
console.log(catalog.info);

Reference: src/index.js.

new WuCore

Creates an instance with its own store or one deliberately injected.

new WuCore(options?): WuCore

  • Parameters: Optional store, storeBufferSize, and compatibility.
  • Returns: Independent instance; the wu import remains the singleton.
  • Errors: Does not start apps; option/compatibility errors propagate.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: await runtime.destroy() when removing the instance.
import { WuCore, WuStore } from 'wu-framework';
const runtime = new WuCore({ store: new WuStore(512) });

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

wu.setPrincipal

Sets the principal used by mount access control.

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

  • Parameters: role, roles, and permissions such as mount:catalog or mount:*; null clears identity.
  • Returns: The same principal or null; projects auth.principal and reports the change.
  • Errors: A failed store write does not roll back the principal.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: wu.setPrincipal(null) when the session ends.
wu.setPrincipal({ roles: ['catalog-reader'] });

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

wu.getPrincipal

Reads the current principal used by the host.

wu.getPrincipal(): object | null

  • Parameters: No arguments.
  • Returns: Principal reference, or null.
  • Errors: Does not validate the session or query the server.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
console.log(wu.getPrincipal()?.roles);

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

wu.can

Checks whether the principal satisfies an application’s roles.

wu.can(appName: string): boolean

  • Parameters: Registered name; queries normalized manifest roles.
  • Returns: Boolean; apps without roles are considered public.
  • Errors: Does not check entrypoint existence or grant store/bus capabilities.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
if (wu.can('catalog')) await wu.mount('catalog', '#catalog-slot');

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

context.wu

Provides each lifecycle with revocable application authority.

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

  • Parameters: The core supplies context; a facade cannot be constructed from a name.
  • Returns: Frozen facade with events, RPC, contracts, and restricted store.
  • Errors: WU_APP_SCOPE_REVOKED after teardown; WU_CAPABILITY_DENIED when accessing resources without a grant.
  • Permissions: Intersection of manifest.wu.permissions and config.grants; does not expose init, destroy, or global administration.
  • Cleanup: Release your own work in unmount; do not reuse the facade afterward.
wu.define('catalog', {
  mount(container, { wu: appWu }) {
    container.textContent = String(appWu.store.get('catalog.count') ?? 0);
  },
});

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

new WuManifest

Creates a manifest reader and validator with its own cache.

new WuManifest(): WuManifest

  • Parameters: No required arguments.
  • Returns: Instance for load, validate, create, and clearCache.
  • Errors: Does not grant permissions or register apps in a core.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: clearCache() discards cached manifests.
import { WuManifest } from 'wu-framework';
const manifests = new WuManifest();

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

WuManifest.load

Downloads and normalizes wu.json from an app’s base URL.

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

  • Parameters: appUrl: public base; expectedName binds registration identity.
  • Returns: Normalized manifest; a real 404 uses the default manifest.
  • Errors: WU_MANIFEST_LOAD_FAILED, WU_MANIFEST_INVALID, and WU_MANIFEST_NAME_MISMATCH; network/HTML/500 failures are not defaults.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: clearCache(base) when you need to discard the read.
const manifest = await manifests.load('/apps/catalog', { expectedName: 'catalog' });

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

WuManifest.validate

Validates structure, limits, paths, and declarative permissions without granting them.

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

  • Parameters: Your own data object; resource is required in object declarations.
  • Returns: Normalized manifest with frozen snapshots.
  • Errors: WU_MANIFEST_INVALID or identity differing from expectedName.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
const manifest = manifests.validate({ name: 'catalog', entry: 'entry.js', wu: { permissions: [] } });

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

WuManifest.create

Produces a manifest from an identity and declarative configuration.

manifests.create(name, config?): object

  • Parameters: name; config.entry (index.js by default), exports, imports, permissions, roles, metadata, styleMode, version, and folder. Nonempty routes are invalid in wu.routes.
  • Returns: Constructed and validated manifest.
  • Errors: The same structural constraints as validate.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
const manifest = manifests.create('catalog', { entry: 'entry.js' });

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

WuManifest.clearCache

Discards stored manifests so they can be downloaded again.

manifests.clearCache(pattern?): void

  • Parameters: Regular expression string; without a pattern, clears this instance’s entire cache.
  • Returns: void.
  • Errors: An invalid RegExp pattern warns and removes no entries; does not alter compiled core registrations.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
manifests.clearCache('/apps/catalog');

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

wu.compatibility.configure

Configures limited migration bridges between strict and compat-v2 profiles.

wu.compatibility.configure(config): WuCompatibility

  • Parameters: profile, warnings, and ai/plugins/apps/sync options; not an additional sandbox.
  • Returns: The same instance.
  • Errors: Unknown configuration or feature may throw.
  • Permissions: Host only; each bridge must be explicitly enabled.
  • Cleanup: Creates no resources requiring release.
wu.compatibility.configure({ profile: 'strict', warnings: 'once' });

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

wu.compatibility.getConfig

Queries the effective profile and its migration bridges.

wu.compatibility.getConfig(): object

  • Parameters: No arguments.
  • Returns: Compatibility configuration.
  • Errors: Does not establish whether a consumer is using a bridge.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
console.log(wu.compatibility.getConfig());

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

wu.compatibility.getMigrationReport

Reads accumulated compatibility-use warnings.

wu.compatibility.getMigrationReport(): object[]

  • Parameters: No arguments.
  • Returns: Entries with code, message, count, and times.
  • Errors: Records only instrumented usage; not a static analysis of your apps.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
console.table(wu.compatibility.getMigrationReport());

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

wu.compatibility.clearMigrationReport

Resets the migration warning log.

wu.compatibility.clearMigrationReport(): void

  • Parameters: No arguments.
  • Returns: void.
  • Errors: Does not change compatibility options.
  • Permissions: Host only; unavailable in the application facade.
  • Cleanup: Creates no resources requiring release.
wu.compatibility.clearMigrationReport();

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

WuApp.mount

Mounts the wrapper identity and remembers the selector.

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

  • Parameters: Optional selector; uses config.container when omitted.
  • Returns: Promise
  • Errors: Propagates registration/mount failures; missing visibility methods warn without mounting.
  • Permissions: Authority of the core owning the wrapper.
  • Cleanup: Balance with widget.unmount().
await widget.mount('#widget-slot');

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

WuApp.unmount

Releases the wrapper reference or preserves keep-alive.

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

  • Parameters: force removes completely; keepAlive preserves DOM.
  • Returns: Promise
  • Errors: Propagates registration/mount failures; missing visibility methods warn without mounting.
  • Permissions: Authority of the core owning the wrapper.
  • Cleanup: Calls renderer unmount when appropriate.
await widget.unmount({ force: true });

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

WuApp.hide

Hides an instance retained by the wrapper.

widget.hide(): Promise<WuApp>

  • Parameters: No arguments; requires a mounted instance.
  • Returns: Promise
  • Errors: Propagates registration/mount failures; missing visibility methods warn without mounting.
  • Permissions: Authority of the core owning the wrapper.
  • Cleanup: deactivate must pause your own timers.
await widget.hide();

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

WuApp.show

Reactivates the wrapper’s keep-alive instance.

widget.show(): Promise<WuApp>

  • Parameters: No arguments; requires hidden state.
  • Returns: Promise
  • Errors: Propagates registration/mount failures; missing visibility methods warn without mounting.
  • Permissions: Authority of the core owning the wrapper.
  • Cleanup: Finish with unmount afterward.
await widget.show();

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

WuApp.remount

Forces unmount, then mounts again at the chosen target.

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

  • Parameters: Optional selector; retains the last target.
  • Returns: Promise
  • Errors: Propagates registration/mount failures; missing visibility methods warn without mounting.
  • Permissions: Authority of the core owning the wrapper.
  • Cleanup: Destroys the previous renderer.
await widget.remount('#widget-slot');

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

WuApp.reload

Clears available loader/manifest caches and mounts again.

widget.reload(): Promise<WuApp>

  • Parameters: No arguments; uses the remembered target.
  • Returns: Promise
  • Errors: Propagates registration/mount failures; missing visibility methods warn without mounting.
  • Permissions: Authority of the core owning the wrapper.
  • Cleanup: Does not invalidate the browser’s native ESM import cache.
await widget.reload();

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

WuApp.verify

Inspects registration, mounting, and the slot ShadowRoot.

widget.verify(): Promise<object>