wu-framework

v1.2.0

Published

4 days ago

Universal Microfrontends Framework - 13 frameworks, zero config, Shadow DOM isolation

Run React, Vue, Angular, Svelte, Solid, Preact, Lit, Qwik, Alpine.js, Stencil, HTMX, Stimulus, and Vanilla JS micro-apps side by side in the same page. Each app lives in its own Shadow DOM with full CSS isolation. Apps communicate through a shared event bus and store — no tight coupling, no iframes.

Add AI to any app with one line. Connect your own LLM (OpenAI, Anthropic, Ollama) and your app gains context-aware tool calling, autonomous agents, and cross-app orchestration. WebMCP ready for Chrome 146+.

npm install wu-framework

30-Second Demo

import { wu } from 'wu-framework';
import { wuReact } from 'wu-framework/adapters/react';
import { wuVue } from 'wu-framework/adapters/vue';

// Register micro-apps from different frameworks
wuReact.register('cart', CartApp);
wuVue.register('catalog', CatalogApp);

// Mount them — each gets its own Shadow DOM
await wu.mount('cart', '#cart-container');
await wu.mount('catalog', '#catalog-container');

// They talk to each other via events
wu.emit('cart:item-added', { productId: 'SKU-42' });
wu.on('catalog:product-selected', (e) => console.log(e.data));

// Add AI with one line — BYOL (Bring Your Own LLM)
wu.ai.provider('openai', { endpoint: '/api/ai/chat', model: 'gpt-4o' });
wu.ai.action('addToCart', {
  description: 'Add a product to the shopping cart',
  parameters: { productId: { type: 'string', required: true } },
  handler: async (params) => wu.emit('cart:item-added', params),
});

// Now the AI can control your app
await wu.ai.send('Add product SKU-42 to the cart');

Why Wu?

| | Wu Framework | single-spa | Module Federation | iframes | |---|:---:|:---:|:---:|:---:| | Framework adapters | 13 | 4 | 1* | Any | | Shadow DOM isolation | Yes | No | No | Yes (heavy) | | Shared event bus | Built-in | Manual | Manual | postMessage | | Shared store | Built-in | Manual | Manual | No | | Standalone mode | Automatic | No | No | N/A | | AI integration | Built-in | No | No | No | | WebMCP (Chrome 146+) | Built-in | No | No | No | | MCP Server (dev tools) | Built-in | No | No | No | | Dependencies | 0 | 0 | Webpack 5 | N/A | | Bundle size (min) | ~174 KB | ~10 KB | Varies | N/A |

*Module Federation is Webpack-coupled; Wu is bundler-agnostic.

Features

Core

13 Framework Adapters — React, Vue, Angular, Svelte, Solid, Preact, Lit, Qwik, Alpine.js, Stencil, HTMX, Stimulus, Vanilla
Shadow DOM Isolation — CSS and DOM fully sandboxed per app
3 Sandbox Strategies — Shadow DOM, Proxy, iframe — choose per app
3 CSS Isolation Modes — shared, isolated, fully-isolated per app
Event Bus — Namespaced pub/sub with wildcards, replay, and middleware
Shared Store — Cross-app reactive state with dot-path notation and persistence
Plugin System — Extend Wu with lifecycle hooks
Performance Monitor — Mount time, memory, FPS tracking per app
Error Boundaries — Catch and recover from micro-app failures
Keep-Alive — Preserve app state when hiding/showing
Prefetch — Speculation Rules API with automatic fallback chain
Cookie Overrides — QA redirects individual apps to different URLs per-browser
Standalone Mode — Every micro-app works without a shell, zero lock-in

AI (BYOL — Bring Your Own LLM)

4 Paradigms — App→LLM, LLM→App, Autonomous Agent, Cross-App Orchestration
Tool Calling — Register actions the AI executes autonomously
Streaming — Async generator for real-time responses
Multi-turn — Namespaced conversations with history
Reactive Triggers — Events automatically invoke the AI
Auto Context — Store state, apps, events injected into the system prompt
10 Browser Actions — Screenshot, click, type, navigate, read console/network
WebMCP — wu.ai.expose() registers tools via navigator.modelContext (Chrome 146+)
MCP Server — Connect Claude Code, Cursor, or any MCP client to your live app
4-Layer Security — Permissions, rate limiting, circuit breaker, loop protection
Workflows — Reusable parameterized AI recipes

Quick Start

1. Register your micro-app

// React
import { wuReact } from 'wu-framework/adapters/react';
wuReact.register('orders', App);

// Vue
import { wuVue } from 'wu-framework/adapters/vue';
wuVue.register('products', App);

// Angular (standalone)
import { wuAngular } from 'wu-framework/adapters/angular';
wuAngular.registerStandalone('settings', AppComponent, { createApplication, createComponent });

// Svelte 5
import { wuSvelte } from 'wu-framework/adapters/svelte';
wuSvelte.registerSvelte5('dashboard', App);

// Qwik
import { wuQwik } from 'wu-framework/adapters/qwik';
wuQwik.register('widget', QwikApp);

// Alpine.js
import { wuAlpine } from 'wu-framework/adapters/alpine';
wuAlpine.register('search', initFn);

// Stencil (Web Components)
import { wuStencil } from 'wu-framework/adapters/stencil';
wuStencil.register('badge', 'my-badge');

// HTMX
import { wuHtmx } from 'wu-framework/adapters/htmx';
wuHtmx.register('feed', { template: '<div hx-get="/api/feed">...</div>' });

// Stimulus
import { wuStimulus } from 'wu-framework/adapters/stimulus';
wuStimulus.register('form', { controllers: { hello: HelloController }, template: '...' });

// Same pattern for Solid, Preact, Lit, Vanilla

2. Mount from the shell

import { wu } from 'wu-framework';

await wu.init({
  apps: [
    { name: 'header',  url: 'http://localhost:3001' },
    { name: 'sidebar', url: 'http://localhost:3002' },
    { name: 'content', url: 'http://localhost:3003' },
  ]
});

await wu.mount('header',  '#header-container');
await wu.mount('sidebar', '#sidebar-container');
await wu.mount('content', '#content-container');

3. Cross-app communication

import { emit, on, getState, setState } from 'wu-framework';

// Events
emit('user:login', { userId: 123 });
on('user:*', (event) => console.log(event.data));

// Shared store
setState('user.name', 'John');
getState('user.name'); // 'John'

4. Add AI (optional)

wu.ai.provider('ollama', {
  endpoint: 'http://localhost:11434/api/chat',
  model: 'llama3',
});

const response = await wu.ai.send('What apps are mounted?');

WuCommerce — Real-World Example

Wu ships with WuCommerce, a Shopify-like merchant dashboard where every section is a real micro-app built with a different framework.

| Micro-app | Framework | What it does | |-----------|-----------|-------------| | Topbar | Preact | Store name, nav tabs, search, notifications, theme toggle | | Dashboard | Svelte 5 | KPI cards, sparklines, recent orders, revenue chart | | Orders | React | Order table with filters, search, status badges | | Products | Vue 3 | Product catalog grid, stock badges, category filter | | Customers | Solid.js | Customer list, segment badges, click-to-filter-orders | | Analytics | Lit | Revenue bar chart, traffic donut, top products | | Chat | Vanilla JS | Floating chat widget with conversations and messages | | Settings | Angular 21 | Store config form, shipping zones, payment methods |

All 8 apps communicate through Wu's event bus and shared store. Click a customer → orders filter. Toggle theme → all 8 apps update. Change store name in settings → topbar updates.

3 Sandbox Strategies

| Mode | How it works | Tree shaking | Source maps | HMR | JS isolation | |------|-------------|:---:|:---:|:---:|:---:| | module (default) | import() + Proxy side-effect tracking | Yes | Yes | Yes | Side effects only | | strict | Hidden iframe + real import() | Yes | Yes | Yes | Full (separate window) | | eval | Fetch HTML → parse → with(proxy){} | No | No | No | Full (proxy traps) |

await wu.init({
  apps: [
    { name: 'header',    url: '...', sandbox: 'module' },
    { name: 'analytics', url: '...', sandbox: 'strict' },
    { name: 'legacy',    url: '...', sandbox: 'eval' },
  ]
});

Auto-cleaned on unmount: timers, intervals, rAF, event listeners, localStorage keys, DOM mutations.

3 CSS Isolation Modes

| Mode | What happens | When to use | |------|-------------|-------------| | shared | Host styles injected into Shadow DOM | Apps sharing a design system (Tailwind) | | isolated | Pure Shadow DOM — no external styles | Fully independent apps | | fully-isolated | Only the app's own styles | Apps that need their CSS but not global CSS |

{ "name": "my-app", "entry": "index.js", "styleMode": "isolated" }

AI Paradigms

1. App → LLM → App

const response = await wu.ai.send('What items are in the cart?');

2. LLM → App → LLM (WebMCP)

wu.ai.expose(); // Registers all tools via navigator.modelContext (Chrome 146+)

3. Autonomous Agent

for await (const step of wu.ai.agent('Find the top customer and show their profile')) {
  console.log(`Step ${step.step}: ${step.content}`);
}

4. Cross-App Orchestration

const result = await wu.ai.intent('Find customer Emma and refund order #4821');
console.log(result.appsInvolved); // ['customers', 'orders']

Plugins & Hooks

import { usePlugin, createPlugin, useHook } from 'wu-framework';

usePlugin(createPlugin({
  name: 'analytics',
  install: (api) => api.on('app:mounted', (e) => track(e)),
  afterMount: async (ctx) => log('mounted in', ctx.mountTime, 'ms')
}));

useHook('beforeMount', async (context, next) => {
  console.log('Mounting:', context.appName);
  await next();
});

Phases: beforeInit → afterInit → beforeLoad → afterLoad → beforeMount → afterMount → beforeUnmount → afterUnmount

Prefetch (Speculation Rules API)

wu.prefetch(['sidebar', 'analytics']);
wu.prefetch(['sidebar'], { trigger: 'hover', action: 'prerender' });
wu.prefetchAll();

Fallback chain: Speculation Rules API (Chrome 121+) → <link rel="modulepreload"> → <link rel="prefetch">

Cookie Overrides for QA

wu.override('sidebar', 'http://localhost:5174');
wu.getOverrides();   // { sidebar: 'http://localhost:5174' }
wu.removeOverride('sidebar');

QA sets a cookie → only their browser sees the override. Everyone else sees production. 3-layer security: environment gate, domain allowlist, visual indicator.

Project Stats

| Metric | Value | |---|---| | Source files | 79 | | Lines of code | 23,442 | | Test cases | 650 | | Framework adapters | 13 | | AI modules | 12 | | Core modules | 23 | | Runtime dependencies | 0 | | Bundle (ESM, minified) | ~174 KB |

Build

npm run build          # ESM + CJS + UMD + Dev
npm run test           # 650 tests (Vitest)
npm run test:coverage  # Coverage report

| Output | Format | Use | |--------|--------|-----| | wu-framework.esm.js | ES Module | Bundler imports | | wu-framework.cjs.js | CommonJS | Node.js require | | wu-framework.umd.js | UMD | CDN / script tag | | www.wu-framework.com.js | ES Module | Development |

Architecture

┌───────────────────────────────────────────────────────────────────────┐
│                       SHELL (any framework)                          │
├──────────┬──────────┬──────────┬──────────┬──────────┬───────────────┤
│ Shadow   │ Shadow   │ Shadow   │ Shadow   │ Shadow   │ Shadow   ...  │
│ ┌──────┐ │ ┌──────┐ │ ┌──────┐ │ ┌──────┐ │ ┌──────┐ │ ┌──────┐    │
│ │Topbar│ │ │Dashbd│ │ │Orders│ │ │Produc│ │ │Custo.│ │ │Analyt│    │
│ │Preact│ │ │Svelte│ │ │React │ │ │Vue 3 │ │ │Solid │ │ │ Lit  │    │
│ └──────┘ │ └──────┘ │ └──────┘ │ └──────┘ │ └──────┘ │ └──────┘    │
├──────────┴──────────┴──────────┴──────────┴──────────┴───────────────┤
│                       WU FRAMEWORK CORE                              │
│  Sandbox (module/strict/eval) · EventBus (wildcards, replay)         │
│  Store (dot-paths, batch) · StyleBridge (shared/isolated/fully-iso)  │
│  Loader · Hooks · Plugins · Cache · Prefetch · Overrides             │
├──────────────────────────────────────────────────────────────────────┤
│                       WU AI (BYOL)                                   │
│  Provider · Actions · Agent · Orchestrate · Triggers · Context       │
│  Browser Actions · WebMCP · MCP Server · Workflows · Security        │
└──────────────────────────────────────────────────────────────────────┘

Documentation

Full documentation at www.wu-framework.com

Quick Start — Get running in 5 minutes
Getting Started — Deeper tutorial with cross-app communication
API Reference — Full API docs
Event Bus — Inter-app communication
Shared Store — Cross-app reactive state
Sandbox — JS isolation strategies
AI Overview — 4 AI paradigms
AI Actions — Register tools for the LLM
Browser Actions — 10 built-in browser tools
MCP Server — Connect AI agents to live apps
CSS Isolation — Shadow DOM style modes
Deployment — Production deployment guide

Browser Support

Chrome 80+, Firefox 78+, Safari 14+, Edge 80+. Shadow DOM v1 required.

What if Wu Framework could think without thinking?

User: "add to cart"

                  Before                              After
                  ──────                              ─────
          wu.ai.send() → LLM                 wu.ai.send() → ???
          ~2,000 ms                           ~0.73 ms
          $0.003 per call                     $0.000

Something is coming. It learned from every LLM call you ever made. It doesn't need the cloud anymore.

99.79% accuracy. 0.73 milliseconds. 800 KB. Zero GPU. Zero internet.

274x faster than neural networks. And it dreams.

COMING SOON

Wu CLI

The official CLI for wu-framework. One binary, one port, all your micro-apps.

npm install -g @wu-framework/cli

wu create my-project    # Interactive scaffolding (13 frameworks)
cd my-project
wu dev                  # Native Zig dev server on one port
wu build                # Production build (parallel Vite)
wu serve                # Serve production build

Features:

Native SIMD HTTP server written in Zig (16 bytes/cycle parsing)
Three-tier compilation: Native Zig JSX (0-2ms) -> Compiler Daemon (10-50ms) -> Node fallback
Two-level cache with 73-138x speedup on warm restart
Theme-aware production shell with dark/light toggle
13 framework app templates with CSS variable theming

See @wu-framework/cli for full documentation.

Contributing

Contributions welcome. Please open an issue first to discuss what you'd like to change.

License

MIT -- Free for personal and commercial use.

See LICENSE-COMMERCIAL.md for optional enterprise support and consulting.

2026 Wu Framework