@atolljs/cli 0.1.5 → 0.1.6

package/README.md

@@ -20,11 +20,15 @@ builds it automatically before staging.
 ## Commands
 
 ```bash
-atoll new <dir> [--framework react|vue|solid|svelte|node] [--pm npm]
+atoll new <dir> [--framework react|vue|solid|svelte|node] [--mfe] [--pm npm]
     Scaffold a fresh app: vite shell with COOP/COEP headers, the
     @atolljs/vite plugin (worker entries are dev-bundled — no
     fast-refresh in workers), a worker-rendered counter island,
     hardened .npmrc — or a tsx Node service with a pooled worker.
+    --mfe instead scaffolds a publishable micro-frontend package:
+    contract + worker entry + vite.mfe.config.ts (emits a
+    self-contained remote bundle) + a dev harness mounting the
+    island through the contract.
 
 atoll init
     Wire Atoll into the current project: .npmrc, installs the @atolljs/*
@@ -34,6 +38,10 @@ atoll init
 atoll add worker <name>   pooled worker + typed client (browser or node)
 atoll add memory <name>   shared-memory contract module
 atoll add island <name>   worker-rendered component for your framework
+atoll add mfe <name>      publishable micro-frontend — framework-free
+                          contract (defineIslandContract) + worker entry
+                          attaching it + vite.mfe.config.ts publish build
+                          → dist-mfe/<name>.worker.js behind CORS
 
 atoll doctor [--fix]      verify deps, lockfile, .npmrc policy,
                           worker-entry detectability, COOP/COEP headers

package/dist/cli.js

@@ -1266,6 +1266,501 @@ const ${P}Island = lazyIsland(() => import('./islands/${name}.island'));
       return "";
   }
 }
+function mfeContractFile(name, fw) {
+  const c = camel(name);
+  const ext = ISLAND_EXT[fw] ?? "ts";
+  return {
+    path: `${name}.contract.ts`,
+    content: `import { z } from '@atolljs/core';
+import { defineIslandContract } from '@atolljs/islands';
+
+/**
+ * '${name}' \u2014 the wire contract for this micro-frontend. Shells import THIS
+ * module only: it names the app, pins the prop/event payload shapes, and
+ * carries the worker factory. The worker attaches the same module via
+ * { contract } so both sides validate one shape \u2014 drift fails loudly at
+ * mount or emit.
+ *
+ * The factory below is bundler-detectable (\`new URL(..., import.meta.url)\`)
+ * so local dev builds the worker entry automatically. Deployment changes
+ * only this field \u2014 see docs/islands-remote.md for the serving rules:
+ *
+ *   // CDN deploy \u2014 worker SCRIPT urls must stay same-origin (a cross-origin
+ *   // new Worker() throws SecurityError regardless of CORS), so the remote
+ *   // bundle loads through a same-origin blob: shim; CORS covers the
+ *   // import fetch inside it:
+ *   worker: () => {
+ *     const shim = \`import \${JSON.stringify(\`\${import.meta.env.VITE_MFE_ORIGIN}/${name}.worker.js\`)};\`;
+ *     return new Worker(
+ *       URL.createObjectURL(new Blob([shim], { type: 'text/javascript' })),
+ *       { type: 'module' },
+ *     );
+ *   },
+ *
+ *   // Or ship dist-mfe/ INSIDE the npm package \u2014 resolve the bundle
+ *   // package-relative as a plain ASSET (hoisted new URL \u2014 inline inside
+ *   // new Worker would make the consumer's bundler re-emit it as a worker
+ *   // entry instead of copying it verbatim):
+ *   const bundled = new URL('../../dist-mfe/${name}.worker.js', import.meta.url);
+ *   worker: () => new Worker(bundled, { type: 'module' }),
+ */
+export const ${c}Contract = defineIslandContract({
+  app: '${name}',
+  props: z.object({ label: z.string().optional() }),
+  events: {
+    incremented: z.object({ count: z.number(), label: z.string() }),
+  },
+  worker: () =>
+    new Worker(new URL('./${name}.worker.${ext}', import.meta.url), { type: 'module' }),
+});
+
+export default ${c}Contract;
+`
+  };
+}
+function mfeWorkerFiles(name, fw) {
+  const P = pascal(name);
+  const c = camel(name);
+  switch (fw) {
+    case "react":
+      return [
+        {
+          path: `${name}.worker.tsx`,
+          content: `import { useState } from 'react';
+import { defineReactMonoWorker, emit } from '@atolljs/react-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/**
+ * ${P} \u2014 a publishable React micro-frontend rendered INSIDE its own worker.
+ * The bundle is self-contained; deploy it behind CORS + a versioned URL.
+ */
+function ${P}({ label = '${name}' }: { label?: string }) {
+  const [count, setCount] = useState(0);
+  return (
+    <button
+      onClick={() => {
+        const n = count + 1;
+        setCount(n);
+        emit('incremented', { count: n, label }); // validates against the contract
+      }}
+    >
+      {label}: {count}
+    </button>
+  );
+}
+
+export const worker = defineReactMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "vue":
+      return [
+        {
+          path: `${P}.vue`,
+          content: `<script setup lang="ts">
+import { ref } from 'vue';
+import { emit } from '@atolljs/islands/worker';
+
+// Rendered inside the worker \u2014 ops stream to the shell; emit() validates
+// the payload against the contract before it leaves the worker.
+const props = defineProps<{ label?: string }>();
+const count = ref(0);
+function increment() {
+  count.value += 1;
+  emit('incremented', { count: count.value, label: props.label ?? '${name}' });
+}
+</script>
+
+<template>
+  <button @click="increment">{{ label ?? '${name}' }}: {{ count }}</button>
+</template>
+`
+        },
+        {
+          path: `${name}.worker.ts`,
+          content: `import { defineVueMonoWorker } from '@atolljs/vue-island/worker';
+import ${P} from './${P}.vue';
+import ${c}Contract from './${name}.contract';
+
+/** '${name}' \u2014 publishable Vue MFE, one app per worker. */
+export const worker = defineVueMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "solid":
+      return [
+        {
+          path: `${name}.worker.tsx`,
+          content: `import { createSignal } from 'solid-js';
+import { defineSolidMonoWorker, emit } from '@atolljs/solid-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/** ${P} \u2014 a publishable Solid MFE rendered inside its own worker. */
+function ${P}(props: { label?: string }) {
+  const [count, setCount] = createSignal(0);
+  return (
+    <button
+      onClick={() => {
+        const n = count() + 1;
+        setCount(n);
+        emit('incremented', { count: n, label: props.label ?? '${name}' });
+      }}
+    >
+      {props.label ?? '${name}'}: {count()}
+    </button>
+  );
+}
+
+export const worker = defineSolidMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "svelte":
+      return [
+        {
+          path: `${P}.svelte`,
+          content: `<script lang="ts">
+  import { emit } from '@atolljs/islands/worker';
+
+  // Rendered inside the worker \u2014 emit() validates against the contract.
+  let { label = '${name}' }: { label?: string } = $props();
+  let count = $state(0);
+  function increment() {
+    count += 1;
+    emit('incremented', { count, label });
+  }
+</script>
+
+<button onclick={increment}>{label}: {count}</button>
+`
+        },
+        {
+          path: `${name}.worker.ts`,
+          content: `import { defineSvelteMonoWorker } from '@atolljs/svelte-island/worker';
+import ${P} from './${P}.svelte';
+import ${c}Contract from './${name}.contract';
+
+/** '${name}' \u2014 publishable Svelte MFE, one app per worker. */
+export const worker = defineSvelteMonoWorker(${P}, { contract: ${c}Contract });
+`
+        }
+      ];
+    case "angular":
+      return [
+        {
+          path: `${name}.worker.ts`,
+          content: `import '@angular/compiler'; // JIT \u2014 compiles the decorator template in the worker
+import { Component, input, output } from '@angular/core';
+import { defineAngularMonoWorker } from '@atolljs/angular-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/**
+ * ${P}Component \u2014 a publishable Angular MFE. The contract is checked against
+ * this class's input()/output() surface (IslandContract<IslandInputs<C>,
+ * IslandEvents<C>>) \u2014 a contract missing 'label' or 'incremented' fails
+ * typecheck HERE, not at the shell.
+ */
+@Component({
+  selector: 'mfe-${name}',
+  template: \`<button (click)="increment()">{{ label() }}: {{ count }}</button>\`,
+})
+export class ${P}Component {
+  readonly label = input('${name}');
+  readonly incremented = output<{ count: number; label: string }>();
+  count = 0;
+  increment(): void {
+    this.count += 1;
+    this.incremented.emit({ count: this.count, label: this.label() });
+  }
+}
+
+export const worker = defineAngularMonoWorker(${P}Component, {
+  contract: ${c}Contract,
+});
+`
+        }
+      ];
+    default:
+      return [];
+  }
+}
+function mfeFiles(name, fw, dir) {
+  return [
+    { ...mfeContractFile(name, fw), path: `${dir}/${name}.contract.ts` },
+    ...mfeWorkerFiles(name, fw).map((f) => ({ ...f, path: `${dir}/${f.path}` }))
+  ];
+}
+function mfePublishConfig(name, fw, dir = "src/mfe") {
+  const ext = ISLAND_EXT[fw] ?? "ts";
+  const plugin = SCAFFOLDS[fw]?.vitePlugin;
+  return `import { defineConfig } from 'vite';
+${plugin?.import_ ?? ""}
+/**
+ * MFE publish build \u2014 emits ONE self-contained ESM worker bundle at
+ * dist-mfe/${name}.worker.js (worker entry + framework runtime baked in;
+ * every remote import would need its own CORS headers, so ship one file).
+ *
+ * Serve it cross-origin with:
+ *   Access-Control-Allow-Origin: <shell origin>   // module workers fetch via CORS
+ *   Cache-Control: public, max-age=31536000, immutable
+ * and version the URL per release \u2014 the contract's worker factory is the
+ * cache key. docs/islands-remote.md covers the full matrix.
+ *
+ *   npm run build:mfe     \u2192 dist-mfe/${name}.worker.js
+ *   npm run preview:mfe   \u2192 serves dist-mfe with the CORS header below \u2014
+ *                           shells still need a same-origin shim entry
+ *                           (blob: or a local re-export file) since worker
+ *                           script URLs can't be cross-origin
+ */
+export default defineConfig({
+  plugins: [
+    {
+      // The worker entry imports the contract, so the contract's own worker
+      // factory lands in this bundle too \u2014 and its new URL(...) resolves
+      // the PREVIOUS dist-mfe output, inlining it into its own successor
+      // (the bundle grows every rebuild). The field is dead code here \u2014 a
+      // worker never spawns itself \u2014 so stub the URL before vite's asset
+      // plugin can resolve it.
+      name: 'mfe:stub-worker-url',
+      enforce: 'pre',
+      transform(code: string, id: string) {
+        if (!id.endsWith('${name}.contract.ts')) return null;
+        return code.replace(
+          /new URL\\(\\s*'[^']*'\\s*,\\s*import\\.meta\\.url,?\\s*\\)/,
+          "'about:blank'",
+        );
+      },
+    },
+    ${plugin?.call ?? ""}
+  ],
+  // App builds define process.env.NODE_ENV automatically; a lib-mode worker
+  // bundle doesn't, and framework dev/prod checks crash on a bare
+  // \`process\` in a browser worker.
+  define: { 'process.env.NODE_ENV': '"production"' },
+  build: {
+    outDir: 'dist-mfe',
+    minify: true,
+    lib: {
+      entry: '${dir}/${name}.worker.${ext}',
+      formats: ['es'],
+      fileName: () => '${name}.worker.js',
+    },
+  },
+  preview: {
+    headers: { 'Access-Control-Allow-Origin': '*' },
+  },
+});
+`;
+}
+function mfeUsage(name, fw, dir = "src/mfe") {
+  const c = camel(name);
+  const consume = {
+    react: `import { islandComponent } from '@atolljs/react-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island label="${name}" onEvent={(n, p) => console.log(n, p)} />`,
+    vue: `import { islandComponent } from '@atolljs/vue-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island v-bind="{ label: '${name}', onEvent }" />`,
+    solid: `import { islandComponent } from '@atolljs/solid-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island label="${name}" onEvent={(n, p) => console.log(n, p)} />`,
+    svelte: `import { island } from '@atolljs/svelte-island';
+import ${c}Contract from './${dir}/${name}.contract';
+<div use:island={{ app: ${c}Contract, props: { label: '${name}' }, onEvent }} />`,
+    angular: `import { islandComponent } from '@atolljs/angular-island';
+import ${c}Contract from './${dir}/${name}.contract';
+export const ${pascal(name)}Island = islandComponent({
+  contract: ${c}Contract,
+  selector: '${name}-island',
+});
+// <${name}-island [props]="{ label: '${name}' }" [onEvent]="onEvent" />`
+  };
+  return `shell side \u2014 mount through the contract, no framework import:
+${consume[fw] ?? ""}
+
+publish \u2014 \`vite build --config vite.mfe.config.ts\` emits dist-mfe/${name}.worker.js
+deploy it behind Access-Control-Allow-Origin + a versioned URL, then point the
+contract's worker factory at it (docs/islands-remote.md).`;
+}
+function mfeScaffoldFiles(appName, fw) {
+  const spec = SCAFFOLDS[fw];
+  if (!spec) return [];
+  const name = appName;
+  const P = pascal(name);
+  const files = [
+    {
+      path: "package.json",
+      content: JSON.stringify(
+        {
+          name: appName,
+          private: true,
+          type: "module",
+          // The package's PUBLIC surface is the contract module — shells
+          // import it, never the worker entry. The worker ships as a
+          // deployed asset (dist-mfe/) referenced by URL, not an import.
+          exports: { ".": `./src/mfe/${name}.contract.ts` },
+          files: ["src/mfe", "dist-mfe"],
+          scripts: {
+            dev: "vite",
+            "build:mfe": "vite build --config vite.mfe.config.ts",
+            "preview:mfe": "vite preview --config vite.mfe.config.ts"
+          },
+          dependencies: spec.deps,
+          devDependencies: spec.devDeps
+        },
+        null,
+        2
+      ) + "\n"
+    },
+    { path: "tsconfig.json", content: JSON.stringify(TSCONFIGS[fw], null, 2) + "\n" },
+    { path: "vite.config.ts", content: viteConfig(fw) },
+    { path: "vite.mfe.config.ts", content: mfePublishConfig(name, fw) },
+    { path: ".npmrc", content: NPMRC },
+    { path: ".gitignore", content: GITIGNORE + "dist-mfe/\n" },
+    { path: "index.html", content: INDEX_HTML(appName, `src/main.${ISLAND_EXT[fw]}`) },
+    ...mfeFiles(name, fw, "src/mfe")
+  ];
+  switch (fw) {
+    case "react":
+      files.push(
+        {
+          path: "src/main.tsx",
+          content: `import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`
+        },
+        {
+          path: "src/App.tsx",
+          content: `import { islandComponent } from '@atolljs/react-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+
+/** Dev harness \u2014 this page mounts the MFE exactly like a consuming shell. */
+export function App() {
+  return (
+    <main style={{ fontFamily: 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>
+        This island renders in a worker. Publish with{' '}
+        <code>npm run build:mfe</code> \u2192 <code>dist-mfe/</code>.
+      </p>
+      <${P}Island
+        label="${name}"
+        onEvent={(name, payload) => console.log('mfe event:', name, payload)}
+      />
+    </main>
+  );
+}
+`
+        }
+      );
+      break;
+    case "vue":
+      files.push(
+        { path: "src/env.d.ts", content: `declare module '*.vue';
+` },
+        {
+          path: "src/main.ts",
+          content: `import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).mount('#root');
+`
+        },
+        {
+          path: "src/App.vue",
+          content: `<script setup lang="ts">
+import { islandComponent } from '@atolljs/vue-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+const onEvent = (name: string, payload: unknown) => console.log('mfe event:', name, payload);
+</script>
+
+<template>
+  <main style="font-family: system-ui; padding: 2rem">
+    <h1>${appName}</h1>
+    <p>This island renders in a worker \u2014 <code>npm run build:mfe</code> publishes it.</p>
+    <${P}Island v-bind="{ label: '${name}', onEvent }" />
+  </main>
+</template>
+`
+        }
+      );
+      break;
+    case "solid":
+      files.push(
+        {
+          path: "src/main.tsx",
+          content: `import { render } from 'solid-js/web';
+import { App } from './App';
+
+render(() => <App />, document.getElementById('root')!);
+`
+        },
+        {
+          path: "src/App.tsx",
+          content: `import { islandComponent } from '@atolljs/solid-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+
+/** Dev harness \u2014 mounts the MFE exactly like a consuming shell. */
+export function App() {
+  return (
+    <main style={{ 'font-family': 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>
+        This island renders in a worker \u2014 <code>npm run build:mfe</code> publishes it.
+      </p>
+      <${P}Island
+        label="${name}"
+        onEvent={(name, payload) => console.log('mfe event:', name, payload)}
+      />
+    </main>
+  );
+}
+`
+        }
+      );
+      break;
+    case "svelte":
+      files.push(
+        {
+          path: "src/main.ts",
+          content: `import { mount } from 'svelte';
+import App from './App.svelte';
+
+mount(App, { target: document.getElementById('root')! });
+`
+        },
+        {
+          path: "src/App.svelte",
+          content: `<script lang="ts">
+  import { island } from '@atolljs/svelte-island';
+  import ${camel(name)}Contract from './mfe/${name}.contract';
+
+  const onEvent = (name: string, payload: unknown) => console.log('mfe event:', name, payload);
+</script>
+
+<main style="font-family: system-ui; padding: 2rem">
+  <h1>${appName}</h1>
+  <p>This island renders in a worker \u2014 <code>npm run build:mfe</code> publishes it.</p>
+  <div use:island={{ app: ${camel(name)}Contract, props: { label: '${name}' }, onEvent }} />
+</main>
+`
+        }
+      );
+      break;
+  }
+  return files;
+}
 function nestjsModuleFiles(name, dir, opts) {
   const P = pascal(name);
   const memImport = opts.mem ? `import { ${opts.mem.export_} } from '${opts.mem.import_}';
@@ -1790,6 +2285,7 @@ var ADD_KINDS = [
   "worker",
   "memory",
   "island",
+  "mfe",
   "service",
   "method",
   "module",
@@ -1802,6 +2298,7 @@ var KIND_SCOPE = {
   worker: null,
   memory: null,
   island: ISLAND_FRAMEWORKS,
+  mfe: ISLAND_FRAMEWORKS,
   service: ["nestjs"],
   method: ["nestjs"],
   module: ["nestjs"],
@@ -1974,6 +2471,29 @@ bind it: pass ${ctx.io.fmt.accent(`${c}Memory`)} as ${ctx.io.fmt.accent("sharedM
       }
       return 0;
     }
+    case "mfe": {
+      const dir = flag(ctx.args, "dir") ?? rel(join3(project.srcDir, "mfe"));
+      const files = mfeFiles(name, framework, dir);
+      const publishCfg = rel(join3(project.root, "vite.mfe.config.ts"));
+      const dirFromRoot = relative(project.root, join3(ctx.cwd, dir)).replaceAll("\\", "/");
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [
+          ...files,
+          { path: publishCfg, content: mfePublishConfig(name, framework, dirFromRoot) }
+        ],
+        force
+      );
+      if (missingDeps(project.pkg, ["vite"]).length) {
+        ctx.io.warn(
+          `vite isn't installed \u2014 the publish build needs it: ${ctx.io.fmt.accent(pmInstallCmd(project.pm, ["-D", "vite"]))}`
+        );
+      }
+      ctx.io.print(ctx.io.fmt.strong("\nwire it:"));
+      ctx.io.print(mfeUsage(name, framework, dir));
+      return 0;
+    }
     case "service": {
       const dir = atollDir;
       mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
@@ -2087,7 +2607,12 @@ async function runCreate(ctx) {
     return 1;
   }
   mkdirSync2(target, { recursive: true });
-  const files = fw === "node" ? nodeScaffoldFiles(dirName) : scaffoldFiles(dirName, fw);
+  const mfe = hasFlag(ctx.args, "mfe");
+  if (mfe && fw === "node") {
+    ctx.io.error("--mfe is a browser-island shape \u2014 pick react|vue|solid|svelte");
+    return 1;
+  }
+  const files = fw === "node" ? nodeScaffoldFiles(dirName) : mfe ? mfeScaffoldFiles(dirName, fw) : scaffoldFiles(dirName, fw);
   await writeTree(ctx.io, target, files, { force: true });
   const written = JSON.parse(readFileSync2(join3(target, "package.json"), "utf8"));
   const allDeps = [
@@ -2104,6 +2629,14 @@ async function runCreate(ctx) {
   );
   ctx.io.print("");
   ctx.io.print(`done \u2014 ${ctx.io.fmt.accent(`cd ${dirName} && ${pm} run dev`)}`);
+  if (mfe) {
+    ctx.io.print(
+      `  ${ctx.io.fmt.accent("npm run build:mfe")} \u2192 dist-mfe/${dirName}.worker.js \u2014 publish behind CORS + a versioned URL`
+    );
+    ctx.io.print(
+      `  ${ctx.io.fmt.accent("npm run preview:mfe")} serves it cross-origin; shells mount the contract`
+    );
+  }
   return 0;
 }
 function runDoctor(ctx) {
@@ -2195,9 +2728,10 @@ function runDoctor(ctx) {
 // src/cli.ts
 var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 bootstrap multithreading ${fmt.dim("(experimental)")}
 
-  ${fmt.accent("atoll new <dir>")} [--framework react|vue|solid|svelte|node] [--pm npm]
+  ${fmt.accent("atoll new <dir>")} [--framework react|vue|solid|svelte|node] [--mfe] [--pm npm]
       Scaffold a fresh app \u2014 vite shell + a worker-rendered island,
-      or a tsx Node service with a pooled worker.
+      or a tsx Node service with a pooled worker. --mfe scaffolds a
+      publishable MFE package (contract + worker + bundle build).
 
   ${fmt.accent("atoll init")} [--name app] [--force]
       Wire Atoll into the current project: hardened .npmrc, package
@@ -2207,6 +2741,8 @@ var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 bootstrap multithreading ${fm
       worker      pool + typed client (+ framework bindings on UI projects)
       memory      shared-memory contract
       island      worker-rendered UI \u2014 facade (contract + lazy import) | mono
+      mfe         publishable micro-frontend \u2014 island contract + worker +
+                  vite.mfe.config.ts (build a self-contained remote bundle)
       service     nestjs: @AtollService class facade + pool module + worker
       method      nestjs: @AtollTask method-level offload
       module      nestjs: registerPool boundary module + worker entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "atoll — scaffold worker pools, shared-memory contracts, and framework islands (experimental)",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",

package/src/cli.ts

@@ -16,9 +16,10 @@ import { runAdd, runCreate, runDoctor, runInit, type Ctx } from './commands.ts';
 
 const HELP = (fmt: Fmt) => `${fmt.strong('atoll')} — bootstrap multithreading ${fmt.dim('(experimental)')}
 
-  ${fmt.accent('atoll new <dir>')} [--framework react|vue|solid|svelte|node] [--pm npm]
+  ${fmt.accent('atoll new <dir>')} [--framework react|vue|solid|svelte|node] [--mfe] [--pm npm]
       Scaffold a fresh app — vite shell + a worker-rendered island,
-      or a tsx Node service with a pooled worker.
+      or a tsx Node service with a pooled worker. --mfe scaffolds a
+      publishable MFE package (contract + worker + bundle build).
 
   ${fmt.accent('atoll init')} [--name app] [--force]
       Wire Atoll into the current project: hardened .npmrc, package
@@ -28,6 +29,8 @@ const HELP = (fmt: Fmt) => `${fmt.strong('atoll')} — bootstrap multithreading
       worker      pool + typed client (+ framework bindings on UI projects)
       memory      shared-memory contract
       island      worker-rendered UI — facade (contract + lazy import) | mono
+      mfe         publishable micro-frontend — island contract + worker +
+                  vite.mfe.config.ts (build a self-contained remote bundle)
       service     nestjs: @AtollService class facade + pool module + worker
       method      nestjs: @AtollTask method-level offload
       module      nestjs: registerPool boundary module + worker entry

package/src/commands.ts

@@ -137,6 +137,7 @@ const ADD_KINDS = [
   'worker',
   'memory',
   'island',
+  'mfe',
   'service',
   'method',
   'module',
@@ -152,6 +153,7 @@ const KIND_SCOPE: Record<AddKind, readonly Framework[] | null> = {
   worker: null,
   memory: null,
   island: ISLAND_FRAMEWORKS,
+  mfe: ISLAND_FRAMEWORKS,
   service: ['nestjs'],
   method: ['nestjs'],
   module: ['nestjs'],
@@ -360,6 +362,34 @@ export async function runAdd(ctx: Ctx): Promise<number> {
       return 0;
     }
 
+    case 'mfe': {
+      const dir = flag(ctx.args, 'dir') ?? rel(join(project.srcDir, 'mfe'));
+      const files = T.mfeFiles(name, framework, dir);
+      // The publish build lives at the project root beside vite.config.ts —
+      // it exists only for `vite build --config`, never the app dev server.
+      const publishCfg = rel(join(project.root!, 'vite.mfe.config.ts'));
+      // The config lives at the project root — the lib entry must be
+      // root-relative even when `add` ran from a subdirectory or --dir moved.
+      const dirFromRoot = relative(project.root!, join(ctx.cwd, dir)).replaceAll('\\', '/');
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [
+          ...files,
+          { path: publishCfg, content: T.mfePublishConfig(name, framework, dirFromRoot) },
+        ],
+        force,
+      );
+      if (missingDeps(project.pkg, ['vite']).length) {
+        ctx.io.warn(
+          `vite isn't installed — the publish build needs it: ${ctx.io.fmt.accent(pmInstallCmd(project.pm, ['-D', 'vite']))}`,
+        );
+      }
+      ctx.io.print(ctx.io.fmt.strong('\nwire it:'));
+      ctx.io.print(T.mfeUsage(name, framework, dir));
+      return 0;
+    }
+
     case 'service': {
       const dir = atollDir;
       mkdirSync(join(ctx.cwd, dir), { recursive: true });
@@ -488,8 +518,17 @@ export async function runCreate(ctx: Ctx): Promise<number> {
   }
   mkdirSync(target, { recursive: true });
 
+  const mfe = hasFlag(ctx.args, 'mfe');
+  if (mfe && fw === 'node') {
+    ctx.io.error('--mfe is a browser-island shape — pick react|vue|solid|svelte');
+    return 1;
+  }
   const files =
-    fw === 'node' ? T.nodeScaffoldFiles(dirName) : T.scaffoldFiles(dirName, fw);
+    fw === 'node'
+      ? T.nodeScaffoldFiles(dirName)
+      : mfe
+        ? T.mfeScaffoldFiles(dirName, fw)
+        : T.scaffoldFiles(dirName, fw);
   await writeTree(ctx.io, target, files, { force: true });
 
   const written = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8'));
@@ -507,6 +546,14 @@ export async function runCreate(ctx: Ctx): Promise<number> {
 
   ctx.io.print('');
   ctx.io.print(`done — ${ctx.io.fmt.accent(`cd ${dirName} && ${pm} run dev`)}`);
+  if (mfe) {
+    ctx.io.print(
+      `  ${ctx.io.fmt.accent('npm run build:mfe')} → dist-mfe/${dirName}.worker.js — publish behind CORS + a versioned URL`,
+    );
+    ctx.io.print(
+      `  ${ctx.io.fmt.accent('npm run preview:mfe')} serves it cross-origin; shells mount the contract`,
+    );
+  }
   return 0;
 }
 

package/src/templates.ts

@@ -1143,6 +1143,528 @@ const ${P}Island = lazyIsland(() => import('./islands/${name}.island'));
   }
 }
 
+/* ── mfe — publishable micro-frontend (contract + worker + bundle config) ── */
+
+/**
+ * The framework-free contract — the ONE module both sides import. The
+ * `worker` factory is bundler-detectable for local dev; a comment shows the
+ * remote-URL variant used once the bundle is deployed (islands-remote.md).
+ */
+export function mfeContractFile(name: string, fw: Framework): OutFile {
+  const c = camel(name);
+  const ext = ISLAND_EXT[fw] ?? 'ts';
+  return {
+    path: `${name}.contract.ts`,
+    content: `import { z } from '@atolljs/core';
+import { defineIslandContract } from '@atolljs/islands';
+
+/**
+ * '${name}' — the wire contract for this micro-frontend. Shells import THIS
+ * module only: it names the app, pins the prop/event payload shapes, and
+ * carries the worker factory. The worker attaches the same module via
+ * { contract } so both sides validate one shape — drift fails loudly at
+ * mount or emit.
+ *
+ * The factory below is bundler-detectable (\`new URL(..., import.meta.url)\`)
+ * so local dev builds the worker entry automatically. Deployment changes
+ * only this field — see docs/islands-remote.md for the serving rules:
+ *
+ *   // CDN deploy — worker SCRIPT urls must stay same-origin (a cross-origin
+ *   // new Worker() throws SecurityError regardless of CORS), so the remote
+ *   // bundle loads through a same-origin blob: shim; CORS covers the
+ *   // import fetch inside it:
+ *   worker: () => {
+ *     const shim = \`import \${JSON.stringify(\`\${import.meta.env.VITE_MFE_ORIGIN}/${name}.worker.js\`)};\`;
+ *     return new Worker(
+ *       URL.createObjectURL(new Blob([shim], { type: 'text/javascript' })),
+ *       { type: 'module' },
+ *     );
+ *   },
+ *
+ *   // Or ship dist-mfe/ INSIDE the npm package — resolve the bundle
+ *   // package-relative as a plain ASSET (hoisted new URL — inline inside
+ *   // new Worker would make the consumer's bundler re-emit it as a worker
+ *   // entry instead of copying it verbatim):
+ *   const bundled = new URL('../../dist-mfe/${name}.worker.js', import.meta.url);
+ *   worker: () => new Worker(bundled, { type: 'module' }),
+ */
+export const ${c}Contract = defineIslandContract({
+  app: '${name}',
+  props: z.object({ label: z.string().optional() }),
+  events: {
+    incremented: z.object({ count: z.number(), label: z.string() }),
+  },
+  worker: () =>
+    new Worker(new URL('./${name}.worker.${ext}', import.meta.url), { type: 'module' }),
+});
+
+export default ${c}Contract;
+`,
+  };
+}
+
+/**
+ * Worker entry per framework — the MFE implementation, attaching the
+ * contract ({ contract }) so props parse at mount/updateProps and the
+ * declared emit payload validates inside the worker.
+ */
+export function mfeWorkerFiles(name: string, fw: Framework): OutFile[] {
+  const P = pascal(name);
+  const c = camel(name);
+  switch (fw) {
+    case 'react':
+      return [
+        {
+          path: `${name}.worker.tsx`,
+          content: `import { useState } from 'react';
+import { defineReactMonoWorker, emit } from '@atolljs/react-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/**
+ * ${P} — a publishable React micro-frontend rendered INSIDE its own worker.
+ * The bundle is self-contained; deploy it behind CORS + a versioned URL.
+ */
+function ${P}({ label = '${name}' }: { label?: string }) {
+  const [count, setCount] = useState(0);
+  return (
+    <button
+      onClick={() => {
+        const n = count + 1;
+        setCount(n);
+        emit('incremented', { count: n, label }); // validates against the contract
+      }}
+    >
+      {label}: {count}
+    </button>
+  );
+}
+
+export const worker = defineReactMonoWorker(${P}, { contract: ${c}Contract });
+`,
+        },
+      ];
+    case 'vue':
+      return [
+        {
+          path: `${P}.vue`,
+          content: `<script setup lang="ts">
+import { ref } from 'vue';
+import { emit } from '@atolljs/islands/worker';
+
+// Rendered inside the worker — ops stream to the shell; emit() validates
+// the payload against the contract before it leaves the worker.
+const props = defineProps<{ label?: string }>();
+const count = ref(0);
+function increment() {
+  count.value += 1;
+  emit('incremented', { count: count.value, label: props.label ?? '${name}' });
+}
+</script>
+
+<template>
+  <button @click="increment">{{ label ?? '${name}' }}: {{ count }}</button>
+</template>
+`,
+        },
+        {
+          path: `${name}.worker.ts`,
+          content: `import { defineVueMonoWorker } from '@atolljs/vue-island/worker';
+import ${P} from './${P}.vue';
+import ${c}Contract from './${name}.contract';
+
+/** '${name}' — publishable Vue MFE, one app per worker. */
+export const worker = defineVueMonoWorker(${P}, { contract: ${c}Contract });
+`,
+        },
+      ];
+    case 'solid':
+      return [
+        {
+          path: `${name}.worker.tsx`,
+          content: `import { createSignal } from 'solid-js';
+import { defineSolidMonoWorker, emit } from '@atolljs/solid-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/** ${P} — a publishable Solid MFE rendered inside its own worker. */
+function ${P}(props: { label?: string }) {
+  const [count, setCount] = createSignal(0);
+  return (
+    <button
+      onClick={() => {
+        const n = count() + 1;
+        setCount(n);
+        emit('incremented', { count: n, label: props.label ?? '${name}' });
+      }}
+    >
+      {props.label ?? '${name}'}: {count()}
+    </button>
+  );
+}
+
+export const worker = defineSolidMonoWorker(${P}, { contract: ${c}Contract });
+`,
+        },
+      ];
+    case 'svelte':
+      return [
+        {
+          path: `${P}.svelte`,
+          content: `<script lang="ts">
+  import { emit } from '@atolljs/islands/worker';
+
+  // Rendered inside the worker — emit() validates against the contract.
+  let { label = '${name}' }: { label?: string } = $props();
+  let count = $state(0);
+  function increment() {
+    count += 1;
+    emit('incremented', { count, label });
+  }
+</script>
+
+<button onclick={increment}>{label}: {count}</button>
+`,
+        },
+        {
+          path: `${name}.worker.ts`,
+          content: `import { defineSvelteMonoWorker } from '@atolljs/svelte-island/worker';
+import ${P} from './${P}.svelte';
+import ${c}Contract from './${name}.contract';
+
+/** '${name}' — publishable Svelte MFE, one app per worker. */
+export const worker = defineSvelteMonoWorker(${P}, { contract: ${c}Contract });
+`,
+        },
+      ];
+    case 'angular':
+      return [
+        {
+          path: `${name}.worker.ts`,
+          content: `import '@angular/compiler'; // JIT — compiles the decorator template in the worker
+import { Component, input, output } from '@angular/core';
+import { defineAngularMonoWorker } from '@atolljs/angular-island/worker';
+import ${c}Contract from './${name}.contract';
+
+/**
+ * ${P}Component — a publishable Angular MFE. The contract is checked against
+ * this class's input()/output() surface (IslandContract<IslandInputs<C>,
+ * IslandEvents<C>>) — a contract missing 'label' or 'incremented' fails
+ * typecheck HERE, not at the shell.
+ */
+@Component({
+  selector: 'mfe-${name}',
+  template: \`<button (click)="increment()">{{ label() }}: {{ count }}</button>\`,
+})
+export class ${P}Component {
+  readonly label = input('${name}');
+  readonly incremented = output<{ count: number; label: string }>();
+  count = 0;
+  increment(): void {
+    this.count += 1;
+    this.incremented.emit({ count: this.count, label: this.label() });
+  }
+}
+
+export const worker = defineAngularMonoWorker(${P}Component, {
+  contract: ${c}Contract,
+});
+`,
+        },
+      ];
+    default:
+      return [];
+  }
+}
+
+/** All MFE files rooted at `dir` — contract + worker (+ framework SFCs). */
+export function mfeFiles(name: string, fw: Framework, dir: string): OutFile[] {
+  return [
+    { ...mfeContractFile(name, fw), path: `${dir}/${name}.contract.ts` },
+    ...mfeWorkerFiles(name, fw).map((f) => ({ ...f, path: `${dir}/${f.path}` })),
+  ];
+}
+
+/**
+ * The publish build — `vite build --config vite.mfe.config.ts` emits ONE
+ * self-contained ESM worker bundle per MFE, deployable to any static host.
+ */
+export function mfePublishConfig(name: string, fw: Framework, dir = 'src/mfe'): string {
+  const ext = ISLAND_EXT[fw] ?? 'ts';
+  const plugin = SCAFFOLDS[fw]?.vitePlugin;
+  return `import { defineConfig } from 'vite';
+${plugin?.import_ ?? ''}
+/**
+ * MFE publish build — emits ONE self-contained ESM worker bundle at
+ * dist-mfe/${name}.worker.js (worker entry + framework runtime baked in;
+ * every remote import would need its own CORS headers, so ship one file).
+ *
+ * Serve it cross-origin with:
+ *   Access-Control-Allow-Origin: <shell origin>   // module workers fetch via CORS
+ *   Cache-Control: public, max-age=31536000, immutable
+ * and version the URL per release — the contract's worker factory is the
+ * cache key. docs/islands-remote.md covers the full matrix.
+ *
+ *   npm run build:mfe     → dist-mfe/${name}.worker.js
+ *   npm run preview:mfe   → serves dist-mfe with the CORS header below —
+ *                           shells still need a same-origin shim entry
+ *                           (blob: or a local re-export file) since worker
+ *                           script URLs can't be cross-origin
+ */
+export default defineConfig({
+  plugins: [
+    {
+      // The worker entry imports the contract, so the contract's own worker
+      // factory lands in this bundle too — and its new URL(...) resolves
+      // the PREVIOUS dist-mfe output, inlining it into its own successor
+      // (the bundle grows every rebuild). The field is dead code here — a
+      // worker never spawns itself — so stub the URL before vite's asset
+      // plugin can resolve it.
+      name: 'mfe:stub-worker-url',
+      enforce: 'pre',
+      transform(code: string, id: string) {
+        if (!id.endsWith('${name}.contract.ts')) return null;
+        return code.replace(
+          /new URL\\(\\s*'[^']*'\\s*,\\s*import\\.meta\\.url,?\\s*\\)/,
+          "'about:blank'",
+        );
+      },
+    },
+    ${plugin?.call ?? ''}
+  ],
+  // App builds define process.env.NODE_ENV automatically; a lib-mode worker
+  // bundle doesn't, and framework dev/prod checks crash on a bare
+  // \`process\` in a browser worker.
+  define: { 'process.env.NODE_ENV': '"production"' },
+  build: {
+    outDir: 'dist-mfe',
+    minify: true,
+    lib: {
+      entry: '${dir}/${name}.worker.${ext}',
+      formats: ['es'],
+      fileName: () => '${name}.worker.js',
+    },
+  },
+  preview: {
+    headers: { 'Access-Control-Allow-Origin': '*' },
+  },
+});
+`;
+}
+
+/** Shell-side consume + publish guidance printed after `add mfe`. */
+export function mfeUsage(name: string, fw: Framework, dir = 'src/mfe'): string {
+  const c = camel(name);
+  const consume: Record<string, string> = {
+    react: `import { islandComponent } from '@atolljs/react-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island label="${name}" onEvent={(n, p) => console.log(n, p)} />`,
+    vue: `import { islandComponent } from '@atolljs/vue-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island v-bind="{ label: '${name}', onEvent }" />`,
+    solid: `import { islandComponent } from '@atolljs/solid-island';
+import ${c}Contract from './${dir}/${name}.contract';
+const ${pascal(name)}Island = islandComponent(${c}Contract);
+<${pascal(name)}Island label="${name}" onEvent={(n, p) => console.log(n, p)} />`,
+    svelte: `import { island } from '@atolljs/svelte-island';
+import ${c}Contract from './${dir}/${name}.contract';
+<div use:island={{ app: ${c}Contract, props: { label: '${name}' }, onEvent }} />`,
+    angular: `import { islandComponent } from '@atolljs/angular-island';
+import ${c}Contract from './${dir}/${name}.contract';
+export const ${pascal(name)}Island = islandComponent({
+  contract: ${c}Contract,
+  selector: '${name}-island',
+});
+// <${name}-island [props]="{ label: '${name}' }" [onEvent]="onEvent" />`,
+  };
+  return `shell side — mount through the contract, no framework import:
+${consume[fw] ?? ''}
+
+publish — \`vite build --config vite.mfe.config.ts\` emits dist-mfe/${name}.worker.js
+deploy it behind Access-Control-Allow-Origin + a versioned URL, then point the
+contract's worker factory at it (docs/islands-remote.md).`;
+}
+
+/** `atoll new <dir> --mfe` — a standalone publishable-MFE package. */
+export function mfeScaffoldFiles(appName: string, fw: Framework): OutFile[] {
+  const spec = SCAFFOLDS[fw];
+  if (!spec) return [];
+  const name = appName;
+  const P = pascal(name);
+  const files: OutFile[] = [
+    {
+      path: 'package.json',
+      content:
+        JSON.stringify(
+          {
+            name: appName,
+            private: true,
+            type: 'module',
+            // The package's PUBLIC surface is the contract module — shells
+            // import it, never the worker entry. The worker ships as a
+            // deployed asset (dist-mfe/) referenced by URL, not an import.
+            exports: { '.': `./src/mfe/${name}.contract.ts` },
+            files: ['src/mfe', 'dist-mfe'],
+            scripts: {
+              dev: 'vite',
+              'build:mfe': 'vite build --config vite.mfe.config.ts',
+              'preview:mfe': 'vite preview --config vite.mfe.config.ts',
+            },
+            dependencies: spec.deps,
+            devDependencies: spec.devDeps,
+          },
+          null,
+          2,
+        ) + '\n',
+    },
+    { path: 'tsconfig.json', content: JSON.stringify(TSCONFIGS[fw], null, 2) + '\n' },
+    { path: 'vite.config.ts', content: viteConfig(fw) },
+    { path: 'vite.mfe.config.ts', content: mfePublishConfig(name, fw) },
+    { path: '.npmrc', content: NPMRC },
+    { path: '.gitignore', content: GITIGNORE + 'dist-mfe/\n' },
+    { path: 'index.html', content: INDEX_HTML(appName, `src/main.${ISLAND_EXT[fw]}`) },
+    ...mfeFiles(name, fw, 'src/mfe'),
+  ];
+  // Dev harness — mounts the MFE through its contract so `vite dev` previews
+  // exactly what a consuming shell sees (no worker imports on the page).
+  switch (fw) {
+    case 'react':
+      files.push(
+        {
+          path: 'src/main.tsx',
+          content: `import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`,
+        },
+        {
+          path: 'src/App.tsx',
+          content: `import { islandComponent } from '@atolljs/react-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+
+/** Dev harness — this page mounts the MFE exactly like a consuming shell. */
+export function App() {
+  return (
+    <main style={{ fontFamily: 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>
+        This island renders in a worker. Publish with{' '}
+        <code>npm run build:mfe</code> → <code>dist-mfe/</code>.
+      </p>
+      <${P}Island
+        label="${name}"
+        onEvent={(name, payload) => console.log('mfe event:', name, payload)}
+      />
+    </main>
+  );
+}
+`,
+        },
+      );
+      break;
+    case 'vue':
+      files.push(
+        { path: 'src/env.d.ts', content: `declare module '*.vue';\n` },
+        {
+          path: 'src/main.ts',
+          content: `import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).mount('#root');
+`,
+        },
+        {
+          path: 'src/App.vue',
+          content: `<script setup lang="ts">
+import { islandComponent } from '@atolljs/vue-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+const onEvent = (name: string, payload: unknown) => console.log('mfe event:', name, payload);
+</script>
+
+<template>
+  <main style="font-family: system-ui; padding: 2rem">
+    <h1>${appName}</h1>
+    <p>This island renders in a worker — <code>npm run build:mfe</code> publishes it.</p>
+    <${P}Island v-bind="{ label: '${name}', onEvent }" />
+  </main>
+</template>
+`,
+        },
+      );
+      break;
+    case 'solid':
+      files.push(
+        {
+          path: 'src/main.tsx',
+          content: `import { render } from 'solid-js/web';
+import { App } from './App';
+
+render(() => <App />, document.getElementById('root')!);
+`,
+        },
+        {
+          path: 'src/App.tsx',
+          content: `import { islandComponent } from '@atolljs/solid-island';
+import ${camel(name)}Contract from './mfe/${name}.contract';
+
+const ${P}Island = islandComponent(${camel(name)}Contract);
+
+/** Dev harness — mounts the MFE exactly like a consuming shell. */
+export function App() {
+  return (
+    <main style={{ 'font-family': 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>
+        This island renders in a worker — <code>npm run build:mfe</code> publishes it.
+      </p>
+      <${P}Island
+        label="${name}"
+        onEvent={(name, payload) => console.log('mfe event:', name, payload)}
+      />
+    </main>
+  );
+}
+`,
+        },
+      );
+      break;
+    case 'svelte':
+      files.push(
+        {
+          path: 'src/main.ts',
+          content: `import { mount } from 'svelte';
+import App from './App.svelte';
+
+mount(App, { target: document.getElementById('root')! });
+`,
+        },
+        {
+          path: 'src/App.svelte',
+          content: `<script lang="ts">
+  import { island } from '@atolljs/svelte-island';
+  import ${camel(name)}Contract from './mfe/${name}.contract';
+
+  const onEvent = (name: string, payload: unknown) => console.log('mfe event:', name, payload);
+</script>
+
+<main style="font-family: system-ui; padding: 2rem">
+  <h1>${appName}</h1>
+  <p>This island renders in a worker — <code>npm run build:mfe</code> publishes it.</p>
+  <div use:island={{ app: ${camel(name)}Contract, props: { label: '${name}' }, onEvent }} />
+</main>
+`,
+        },
+      );
+      break;
+  }
+  return files;
+}
+
 /* ── nestjs (`atoll add nestjs <level> <name>`) ─────────────────────────── */
 
 /**