WU CONCEPTS4 MIN READ · MARKDOWN ↗

Configuration and manifests

What the shell configures, what wu.json can declare, and how startup is validated in Framework 4.

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

Two documents with different authority

wu.init() configuration belongs to the shell. wu.json belongs to an application and is downloaded from <url>/wu.json. The manifest requests resources; the shell grants the maximum authority. No manifest field can grant itself permissions.

import { wu } from 'wu-framework';

await wu.init({
  sandbox: 'module',
  strictEvents: true,
  strictFallback: false,
  manifestPolicy: { imports: 'error' },
  apps: [{
    name: 'catalog',
    url: '/apps/catalog',
    framework: 'react',
    container: '#catalog-slot',
    keepAlive: false,
    grants: [
      { capability: 'store.read', resource: 'catalog' },
      { capability: 'events.emit', resource: 'catalog:selected' },
    ],
  }],
});

container configures a target that wu.app() can use. An explicit wu.mount('catalog', '#catalog-slot') call makes each mount’s target visible.

Global options

Option	Initial value / behavior
`apps`	Configuration list with `name` and `url`
`sandbox`	`module`; also `strict` and `eval`
`strictFallback`	`false`; enabling it allows a failed strict load to fall back to eval
`strictEvents`	Forced to `true` on initialization unless explicitly `false`
`eventBus`	Bus settings; `strictEvents` takes precedence over `strictMode`
`manifestPolicy.imports`	`error`; also `warn` and `off`
`overrides`	Settings for the development URL override system
`compatibility`	`strict` profile or explicit migration configuration

init groups concurrent calls, waits for plugin installation, registers apps, and validates imports after all registrations complete. A failed initialization rolls back registrations created in that attempt. After successful initialization, another init call warns and returns: it is not an API for replacing configuration live.

whenReady() returns a promise containing a boolean. If nobody has started WU, it returns false; if startup is pending, it waits for the result. mount() already waits for an in-flight init.

A complete, valid manifest

{
  "name": "catalog",
  "version": "1.2.0",
  "entry": "assets/catalog.js",
  "styleMode": "own-only",
  "wu": {
    "exports": { "ProductCard": "components/product-card.js" },
    "imports": [],
    "permissions": [
      { "capability": "store.read", "resource": "catalog", "required": true },
      { "capability": "events.emit", "resource": "catalog:selected" }
    ],
    "roles": ["catalog-reader"]
  },
  "metadata": {
    "description": "Explorador del catálogo",
    "routes": ["/catalog", "/catalog/:id"]
  }
}

Supported top-level fields are name, entry, wu, metadata, styleMode, version, folder, and roles. Within wu, recognized fields are exports, imports, permissions, roles, and the historical name routes, although nonempty routes there are rejected during Framework 4 normalization. Use metadata.routes for descriptive information.

framework, sandbox, grants, domOwnership, and keepAlive belong to shell configuration. Extra fields are not accepted indiscriminately: store your own metadata inside metadata.

Loading and validation rules

A real 404 allows generation of the default manifest with entry: 'index.js' and empty permissions. A network error, 500, invalid JSON, or HTML page returned as a manifest produces an error. This prevents a misconfigured server from being interpreted as an application without a manifest.

Limit	Value in code
Manifest size	100 KiB
Name length	50 characters
Entry length	200 characters
Exports	100
Declarative imports	50
Descriptive routes	100
Requests / grants	50 declarations per list

Validation checks that the downloaded name matches the registered name. It inspects own properties, rejects accessors and dangerous structures, and returns a frozen snapshot. Do not use manifest.wu.permissions.push(...) to change policy after registration.

Permissions: exact syntax

An object declaration requires capability and an explicit resource. A valid string form is, for example, store.read:catalog. Use an object to also declare required; use a string when you only need a capability and resource.

// Solicitud de la aplicación:
const permission = {
  capability: 'store.read',
  resource: 'catalog',
  required: true,
};

// Dos formas equivalentes de conceder esa lectura desde el host:
const objectGrant = { capability: 'store.read', resource: 'catalog' };
const stringGrant = 'store.read:catalog';

store.read alone is not a valid declaration for the parser. The input TypeScript declaration permits some broader values, so explicitly supplying the resource is necessary even when the editor does not require it.

required defaults to false. A denied optional permission is recorded in diagnostics, and its operation will be rejected if attempted. required: true makes registration fail when the shell does not cover the entire request.

Loading strategy, layout, and styles

strategy selects how to preload an application; see loading and prefetching to choose between loading on mount, importing immediately, or prefetching resources. fullBleed controls whether the app fills the host height or flows with content. Both fields are read from application configuration, although they are not listed in WuAppConfig.

Configure styleMode in the manifest. Mounting passes app.manifest.styleMode to the sandbox; the same-named field in top-level host configuration does not replace it. The sandbox and CSS guide explains how to combine app and shared styles.

Implementation references

Implementation: src/core/wu-core.js, src/core/wu-core.js, src/core/wu-core.js; parser and limits: src/core/wu-manifest.js, src/core/wu-manifest.js, src/core/wu-manifest.js; policy: src/core/wu-policy.js and src/core/wu-policy.js. Tests: tests/unit/manifest-policy.test.js, tests/unit/manifest-dependencies.test.js, tests/unit/init-race.test.js.