Wu Microfrontends

Wu Microfrontends

Produce a working Wu project, not isolated snippets. Operate the Wu CLI and Wu Framework directly. Preserve the user's frameworks, package manager, repository layout, and release channel unless they explicitly request a migration.

Establish the project contract

Before changing files:

1. Locate the project root using wu.config.json, the workspace package.json, or the shell/ plus mf-*/ layout.
2. Inspect installed and locked versions. Wu V3 and CLI 0.5 require Node 20+.
3. Prefer the project-local CLI or an explicitly pinned npx invocation. Do not silently replace latest with beta, or beta with latest; verify registry tags when the user asks for the newest release.
4. Read references/framework-selection.md when choosing frameworks, splitting features, designing shared components, or connecting unlike runtimes.
5. Read references/wu-v3-contract.md when the task touches configuration, manifests, permissions, migration, plugins, AI, WebSocket sync, builds, or deployment.

Honor or choose the framework deliberately

• If the user names a supported framework, use it unless the repository proves it incompatible. Explain any real incompatibility before substituting it.
• In an existing project, preserve each app's framework. Do not rewrite apps merely to make the stack uniform.
• If no choice was made, derive it from the existing stack, team constraints, feature boundary, bundle budget, rendering model, and component-sharing needs. Ask only when the choice materially changes the product contract.
• Use React, Angular, Vue, Svelte, Solid, Preact, Qwik, or another supported adapter for an independently owned feature when that runtime fits its team.
• Consider Lit or Stencil Web Components for framework-neutral visual primitives and design systems. Do not turn an entire bounded feature into a component library.
• Consider Vanilla, Alpine, HTMX, or Stimulus for small or HTML-first features. Astro and Next.js are shell choices, not Wu micro-app adapters.
• Do not use Lit as a substitute for Wu's app-to-app contracts. Share visual elements through Web Components; share state, events, and operations through the app-scoped Wu facade.

Drive the project through Wu

• Select and preserve an explicit CLI version or dist-tag before scaffolding.
• New project: use wu create. For reproducible automation, prefer npx @wu-framework/cli@<version> create <name> --template <app-framework> --shell <shell-framework>.
• Existing project: edit its current structure instead of regenerating it.
• Add an app: use wu add <framework> <name>. For a batch, run each add with --no-install, then run one wu install to consolidate dependency graphs.
• Inspect the generated adapter, lifecycle, wu.json, and wu.config.json entry before adding business logic. Do not hand-roll CLI output when the installed CLI already supports the requested topology.
• Use Wu Framework APIs for lifecycle, events, RPC, stores, plugins, AI, and sync. Keep framework code behind its generated adapter boundary.
• Migration: keep legacy apps on the explicit V2 compatibility bridge only while removing each reported use; new apps stay strict.
• Diagnosis: reproduce first, then use wu info, wu doctor, relevant tests, and the browser only when runtime behavior must be observed.
• Release or deployment: prepare and validate artifacts, but publish, deploy, change npm dist-tags, or mutate cloud state only with explicit authorization.

Keep cross-framework boundaries explicit

• A bounded product feature is a micro-app; a reusable visual primitive may be a Lit or Stencil Web Component; same-framework internals belong in a normal package; nonvisual collaboration belongs in Wu events, RPC, or stores.
• Never import another micro-app's private framework modules. Define versioned, serializable payloads and stable event/RPC names at the boundary.
• For Web Components, use DOM properties for rich input and intentional custom events for DOM output. Bridge cross-app behavior through Wu instead of making unrelated apps query or mutate each other's DOM.
• Use domOwnership: "app" when Lit or another component runtime owns its ShadowRoot. Avoid nested isolation boundaries unless tested and intentional.
• Mount, unmount, and remount cleanly. Dispose framework roots, subscriptions, observers, timers, DOM listeners, RPC providers, and shared-store watchers.

Preserve V3 authority boundaries

Treat app requests and host authority as separate inputs:

• The app requests capabilities in its wu.json.
• The shell grants the maximum allowed authority through apps[].grants.
• Effective authority is their intersection. Never fix a denial by granting a wildcard unless the user explicitly accepts that scope.
• A required denied request must remain a mount error; optional denied requests should remain observable in diagnostics.

Use the app-scoped Wu facade supplied by the lifecycle. Do not reintroduce EventBus identity administration through the public bus. Await plugin installation and pass explicit plugin grants. Keep AI actions and network access deny-by-default, and require authenticated WebSocket peers or an explicitly trusted transport.

Validate observable outcomes

Run checks proportional to the change. For a typical implementation, polyglot addition, or migration, require:

1. unit and framework-specific tests for every touched app, shared component, and shell;
2. contract tests for cross-app event, RPC, store, and Web Component payloads;
3. mount/unmount/remount integration tests for every touched adapter;
4. wu doctor with no unexplained V2 or publication findings;
5. wu build from the project root;
6. inspection of dist/apps.json, dist/wu-manifest.json, and each built app's wu.json, especially hashed entries and preserved permissions;
7. wu serve or the target host's preview, including at least one real cross-framework flow when the project is polyglot.

Do not describe wu serve as a production server. For production, hand the static build to the user's real host and validate its generated security headers, app origins, connect origins, caching, and fallback behavior.

Report exactly what was validated, what remains environment-dependent, and any compatibility bridge or broad grant still present.