@wu-framework/cli

WU CLI

Create, develop, build and diagnose WU microfrontend projects. WU CLI combines a native Zig executable with a small npm launcher, framework scaffolds and the project's own compiler toolchains.

Use @wu-framework/cli to manage the project and wu-framework as the browser runtime. Applications keep their own framework, dependencies and build configuration.

Documentation · npm · Framework · Examples · Support

This README describes 1.2.0. Online documentation is available in English, Simplified Chinese, Portuguese and Spanish. See the changelog for release history.

New in 1.2.0

wu doctor validates framework ranges against the CLI catalog, so the generated Framework 4 projects pass WU_D003. It rejects incompatible or mixed-major ranges and malformed version text instead of inspecting the first digit. Local dependency paths and cross-manifest consistency checks are preserved.

Windows build and managed-process commands preserve quoted paths, arguments and shell operators. A concurrent build reports the PID that holds the project lock, including on Windows.

CLI 1.x capabilities

This release targets WU Framework 4.0.0 and retains existing conventional build workflows. Update framework ranges in existing shell/app packages and run wu install; upgrading the global CLI alone does not change project dependencies.

wu dev refuses file reads outside the project and answers only local hosts unless dev.allowedHosts lists them. wu upgrade brings existing manifests up to the CLI's catalog and wu catalog prints it. wu build writes to a temporary directory, reuses unchanged apps and can sign a deploy with --sign. The executables ship as one npm package per platform.

Builds and development share one WU core. Apps using optional WU subsystems must import their registration entries in the shell; see the upgrade guide. The conventional build can externalize direct Vite invocations; opaque custom build wrappers must configure sharing themselves.

wu build --native follows modules discoverable from server responses. Computed imports and runtime-selected assets may need explicit inclusion or the conventional toolchain. Browser tests require Playwright and an installed browser. The five packaged platforms are cross-compiled; execute your application's validation on each deployment platform you support.

What the CLI does

• Generates a shell and microapps for 13 framework targets, plus Astro and Next shell integrations.
• Aggregates dependencies and supports app-specific dependency versions.
• Serves the project through one HTTP origin in native development mode, with compilation and reload support.
• Runs application builds and assembles their output, manifests and hosting headers in dist/.
• Previews static sites or SPA shells with correct asset 404s and cache policies.
• Diagnoses local projects and deployed HTTP/HTTPS resources, including machine-readable reports and failing exit codes.
• Generates service client declarations and checks schema compatibility using wu-framework/services.
• Runs Node tests and optional Playwright browser lifecycle checks.
• Builds native production/PWA output, generates contract mocks and packages installable apps.

The native development listener can replace a separate Vite dev server for each app. JSX, TypeScript and framework compilation still use Node tooling; production builds use each application's configured toolchain. One HTTP origin does not imply that every workflow uses only one operating-system process.

Install

npm install -g @wu-framework/cli
wu --version
wu --help

The npm launcher requires Node >=20. npm installs the prebuilt executable for your platform with it, as an optional dependency, so do not install with --omit=optional. End users do not need Zig. Frameworks and tools such as Astro or Vite may require a newer Node version; follow their requirements when selecting a project stack.

For a one-off invocation:

npx @wu-framework/cli@1.2.0 --version

npm downloads only the package for the current platform, and the launcher runs its executable. If the package is missing, wu says so and prints the reinstall command (--include=optional). This release still carries all five executables inside @wu-framework/cli too, for one transition release. An unsupported platform fails explicitly. Linux executables are static (musl) and also run on Alpine; bin/SHA256SUMS lists each executable's checksum, and the launcher checks it before the first run. Direct native execution is possible, but compiler operations, remote doctor and contract tooling still need their documented Node/project dependencies.

Create an Astro shell with React and Vue

wu create portal --template react --shell astro
cd portal
wu add vue catalog --no-install
wu install
wu dev --no-open

Open http://127.0.0.1:3000. The generated React application is named portal, and the added Vue application is named catalog. The shell composes them with WU.

The quick create command writes files without installing. add --no-install lets you generate multiple apps before one wu install. The interactive wu create wizard can instead collect a shell and several apps and offer installation at the end.

The generated structure includes:

portal/
  package.json
  wu.config.json
  shell/
    package.json
    astro.config.mjs
    src/pages/index.astro
  mf-portal/
    package.json
    vite.config.js
    src/main.tsx
    src/App.tsx
  mf-catalog/
    package.json
    vite.config.js
    src/main.ts
    src/App.vue

Stop the development server before moving to a production preview:

wu build
wu serve 4100 --mode static

Open http://127.0.0.1:4100. Publishing the contents of dist/ to a hosting provider is a separate deployment step.

Framework and shell choices

Microapp template names are:

react  vue  angular  svelte  preact  solid  lit
vanilla  alpine  qwik  stencil  htmx  stimulus

Use them with wu create <name> --template <framework> and wu add <framework> <name>. Shell selection additionally accepts astro and next; those two are shell integrations, not microapp template names.

The quick path enables TypeScript where the template supports it. HTMX, Alpine and Stimulus remain JavaScript. There is no quick-mode --typescript, --yes, --apps or --package-manager flag. Adapter generation does not imply identical compiler, SSR or HMR behavior across frameworks.

WU Framework can also host other technologies through a custom lifecycle. For an existing app, declare it in wu.config.json, adapt its entry to WU and configure its build command; wu add generates a new scaffold. See the template matrix and adding existing apps.

Command reference

Run project commands from the directory containing wu.config.json.

wu build has no CLI-specific --watch, --app or --out-dir option. Configure the application's build command instead. wu remove, wu deploy, wu status and wu config are not implemented commands in this version. Full aliases and parser behavior are documented in the API reference.

Configuration and dependency ownership

The following explicit configuration matches the quickstart's directories:

{
  "name": "portal",
  "shell": {
    "dir": "shell",
    "framework": "astro",
    "build_cmd": "npx astro build"
  },
  "apps": [
    { "name": "portal", "dir": "mf-portal", "framework": "react", "port": 5001 },
    { "name": "catalog", "dir": "mf-catalog", "framework": "vue", "port": 5002 }
  ],
  "proxy": { "port": 3000, "open_browser": false },
  "security": { "enabled": true }
}

Each shell/app's package.json owns its dependencies. wu install builds an aggregate root manifest and uses .wu-deps.json for per-directory overrides when versions differ. In 1.0.1 it also preserves custom root scripts, metadata and dependencies not claimed by an app. App-declared versions take precedence in the aggregate, and obsolete WU-generated version aliases are removed. Declare app dependencies in their owning application; root-only tooling can remain in the root manifest.

App entries can additionally declare build/dev commands, DOM ownership and host grants. The app's wu.json requests capabilities; host grants do not replace those requests. The scaffold does not create a source wu.json by default: development can synthesize one and production build emits one. Add an explicit manifest when declaring permissions or contracts.

If configuration is absent, supported commands can discover immediate subdirectories. Explicit configuration is more predictable for an existing or mixed project. Malformed configuration disables discovery rather than silently selecting a different topology. See configuration and dependency management.

Development and reload

wu dev --port 3200 --no-open

Native mode binds to loopback HTTP and serves the shell and applications from one origin. It resolves npm imports and invokes the relevant Node/framework compilers on demand. A persistent compiler helper reduces repeated startup work; compiler diagnostics are written to .wu-cache/wu-compiler.log.

Astro and Next shells are served from their generated output and rebuilt when their sources change. Reload behavior depends on the framework and edit; it does not guarantee preservation of every application's local state.

To use per-application development processes instead:

wu dev --vite

This mode uses the configured shell/app commands and ports. Native --port does not rewrite all Vite process ports. The server has no public --host flag in this release. The configured proxy accepts HTTP origins; HTTPS targets require a separate suitable proxy. See development.

Build, serve and deploy

wu build runs the configured build toolchains, places app outputs under dist/<app-directory>/, publishes their manifests and inserts the app catalog into the shell. Output can include apps.json, wu-manifest.json, _headers, vercel.json and wu-security.conf.

Select the preview mode that matches the shell:

Use static mode for Astro exports, documentation and multipage sites. Use SPA mode for a client-routed shell. Both support GET and HEAD. Missing dist/index.html, invalid serve ports and occupied ports fail.

Stable assets, HTML and manifests revalidate. An asset receives immutable caching only when its filename contains a 12–64 digit hexadecimal SHA-256 prefix matching its bytes; other hash formats revalidate. Generated CSP hashes are calculated per HTML document, including nested and 404 pages. An explicitly supplied CSP remains under host control.

The preview listener binds to 127.0.0.1; public routing and TLS belong to the hosting service or reverse proxy. Apply the emitted headers in the format your host expects, preserve code examples with no-transform, and run remote doctor against the deployed result. See build, serve and HTTP security.

Local and remote doctor

wu doctor --json
wu doctor --url https://example.com --route /guide/ --json

Local checks cover project directories, shell output, WU versions, dependency overrides, ports, exposed sensitive files and security headers. The JSON report includes schemaVersion, version, mode, ok, checks, problems and diagnostics with stable category codes.

Remote checks inspect response status, asset MIME types, inline CSP, missing-asset fallbacks and known response transformations. They follow static script/link/iframe references and literal module imports; they do not execute application JavaScript. Add --entry for a dynamically selected app or an explicitly permitted external origin.

wu doctor --url https://example.com --entry /apps/catalog/entry.js --timeout 8000 --json

The scan is bounded to 32 resources, 40 requests, three redirects per resource, 2 MiB per response and 30 seconds overall. The per-response timeout defaults to 5000 ms. Large sites need focused scans. Remote checks send no login credentials; reported URLs omit query strings and fragments.

• Exit 0: no error findings; warnings can remain.
• Exit 1: diagnostic findings, including an empty local project.
• Exit 2: invalid remote options or remote execution failure.

--json prints JSON without ANSI decoration or update notices and does not implicitly probe port 3000. Human-readable local doctor retains the older localhost live check. A successful HTTP scan is not a substitute for browser, accessibility or lifecycle testing. See diagnostic codes and limits.

Service types and compatibility

Install wu-framework >=3.1.0 in the project. Contract commands load its actual wu-framework/services export; the CLI does not maintain a second schema implementation.

For example, save greeting.contract.json:

{
  "name": "greeting",
  "version": "1.0.0",
  "methods": {
    "welcome": {
      "input": { "type": "string", "minLength": 1 },
      "output": { "type": "string" }
    }
  }
}

Generate the client interface:

wu contracts types greeting.contract.json --out greeting-client.d.ts

The JSON uses WU's data-only service schema format, not arbitrary JSON Schema. types writes declarations to stdout when --out is omitted. An output file must be a separate .d.ts file. Input definitions are limited to 1 MiB.

Save the previous definition before making a change, then compare the two revisions:

wu contracts check greeting.previous.json greeting.contract.json --json

# A breaking change shipped with translators for the previous version is compatible:
# the module exports the same array the provider passes to provideService().
wu contracts check greeting.previous.json greeting.contract.json --translators ./translators.mjs
wu contracts types greeting.previous.json greeting.contract.json --out greeting-client.d.ts

Adding a method passes compatibility checking. Removing a method or changing an existing input/output schema returns 1 for review; invalid definitions/options return 2. This is conservative structural checking, not proof of business compatibility or automatic version selection. TypeScript-owned definitions already infer clients through consumeService, so file generation is optional.

See contract tooling and framework service definitions.

Project tests

wu test
wu test --test-name-pattern=cart tests/cart.test.mjs
wu test --browser --channel chrome
wu mock contracts/catalog.json     # mf-catalog-mock/ answers every method of the contract

This dispatches Node's built-in test runner and propagates its exit status. It does not install a DOM or select a browser. Use your existing renderer/browser test setup, or the optional wu-framework/testing lifecycle conformance kit with a fixture that checks visible output and resource cleanup.

Update and troubleshoot

wu update

The npm launcher updates the global CLI. It does not update framework dependencies inside projects. WU_DISABLE_UPDATE_CHECK=1 or a CI environment disables passive update notices; an explicit wu update still performs its requested check.

There is no automatic remove/rename command: update configuration, mounts, navigation and manifests together, then rebuild. Some older generation/install paths have early returns that do not prove an artifact was created; automation should verify output as well as exit status. See installation and the full command reference.

Develop, test and package the CLI

Contributors need Zig 0.16.0 (exactly, for release builds) and Node 22 LTS or newer (CI uses 22). The Zig package has no third-party Zig dependencies.

zig build
zig build test --summary all
npm test
npm run test:native
npm run build:binaries
npm run test:package
npm run test:fuzz

These checks cover different layers: Zig tests (including property tests of the parsers), Node invariants/launcher tests, native command behavior and the six packed, installed npm packages. build:binaries refuses any Zig other than the pinned version, cross-compiles all five targets as stripped ReleaseSafe builds (static musl on Linux), writes one npm package per platform into npm/<os>-<cpu>/ and writes bin/SHA256SUMS. The package check requires each packed file list to be exactly its allowlist, checks versions, os/cpu, every executable's format and architecture against its name and the checksums, installs the tarballs offline so that npm itself picks the platform package, and exercises the native executable through the launcher on the current machine; it does not execute all five architectures locally. test:fuzz runs a short coverage-guided session of every parser fuzz test; CONTRIBUTING.md describes long sessions.

Optional cross-repository checks use WU_FRAMEWORK_TARBALL for npm run test:contracts and a built WU_FRAMEWORK_ROOT for npm run test:conformance. The latter generates an actual vanilla app, compiles it and exercises lifecycle behavior in a browser. See contributor architecture and CONTRIBUTING.md.

Releases are published with node scripts/publish.mjs (a dry run; --yes publishes). It runs the Zig build and tests, npm test, the release build and the package check, refuses a dirty tree or any disagreement between the six versions and bin/SHA256SUMS, then publishes the five platform packages before @wu-framework/cli. A bare npm publish is refused by prepublishOnly.

Documentation map

Team, support and license

• Luis García on LinkedIn
• José García on LinkedIn

Report a bug or suggest an improvement · Support independent development

Include wu --version, your platform/Node version, a minimal reproduction, expected behavior and actual behavior. Review diagnostics before sharing them. WU CLI is MIT licensed.