a platform for microfrontends ✦

◆ Architecture and conventions

Moving parts

The platform is composed of five independent pieces that each do one thing:

The fe() convention

fe(scope/name) is a plain string used as a package name everywhere: in package.json, in import statements, and in the platform manifest. It is a bare specifier that the browser resolves through injected import maps. There is no special URL scheme.

// package.json
{ "name": "fe(acme/my-mfe)" }

// source
import { store } from "fe(acme/store)";

// platform.json
"fe(acme/store)": { "versions": { "1.0.0": { "url": "..." } } }

During build, fe(*) entries in devDependencies are treated as externals. At runtime, the browser resolves each specifier to a URL via the injected import map. The symlinks created by bun install satisfy TypeScript without any tsconfig.paths configuration.

MFE exports

A MFE is a plain ES module and the platform is foundationally TypeScript-based. It can export functions, stores, API clients, or anything else that makes sense for its purpose. The platform treats publish, versioning, and import-map resolution the same regardless of what the module exports.

The one special case is a MFE registered under routes in platform.json. When the runtime matches a URL to that entry, it imports the module and calls render() to mount the UI:

export function render(
  container: HTMLElement,
  props: Record<string, unknown>
): () => void {
  // mount into container
  // return a cleanup function that removes your DOM nodes
}

The contract is intentionally minimal: no framework lifecycle, no router coupling, no shared state requirement. The cleanup function is called on navigation away. React, Solid.js, and vanilla DOM all satisfy it without adaptation.

Deployment model

MFEs are deployed as raw TypeScript source, not as bundles. fe publish uploads source files and registers a new version in platform.json. The JIT server compiles source on first request and responds with Cache-Control: immutable headers.

Artifact URLs include the version, so the compiled output is stable forever. A new publish creates a new URL; old versions remain available at their original addresses. Rollback is a one-line edit to platform.json.

Local development

fe dev <target> starts a dev server for one MFE with SSE-based hot module reload. The devtools overlay (if installed) lets you redirect any fe(scope/name) specifier to a local dev URL via sessionStorage. This override affects only the current browser tab and can be shared as a URL parameter.

fe dev mfe-a          # start dev server at localhost:3001
# in devtools panel: override fe(acme/mfe-a) → http://localhost:3001/

fe check <target> runs typecheck and simulates a build without writing output. Use it in CI to catch errors early without running the full JIT pipeline.

Cross-MFE dependencies

When a MFE depends on another, declare it in devDependencies:

// mfe-b/package.json
{
  "name": "fe(acme/mfe-b)",
  "devDependencies": { "fe(acme/mfe-a)": "^1.0.0" }
}

The runtime reads the dep graph from platform.json and resolves the highest compatible version using semver. All resolved specifiers are injected into a single <script type="importmap"> before the MFE is imported. Subsequent navigations skip specifiers already injected, so shared deps load once.

Extension points

Two plugin systems let organisations extend the platform without forking it:

• CLI plugins — swap adapters at bootstrap time. Replace artifact storage with S3, replace config reading with an environment-variable provider, or add new CLI commands. Declare in fe.config.json under "plugins".
• JIT plugins — transform BuildOptions before each compilation. @fe/jit-plugin-react and @fe/jit-plugin-solid ship out of the box. Declare in fe.config.json under "jitPlugins".

CLI quick reference

fe new <scope/name>   scaffold a new MFE project
fe dev <target>       live-reload dev server
fe check <target>     typecheck + build simulation (CI)
fe publish <target>   upload source + register version
fe link <mfe> <dep>   wire a local fe() dependency
fe build shell        compile the host shell
fe serve              run the JIT server

◆ For product engineers

What you own independently

As a product engineer working on a MFE, you own the full lifecycle of your feature from scaffolding through deployment. The platform team operates the infrastructure; you work entirely from the command line without touching shared CI/CD pipelines or coordination tickets.

• fe new acme/my-feature — scaffold a new MFE in one command.
• fe dev my-feature — hot-reload dev server, live in your browser.
• fe check my-feature — typecheck before pushing; same check runs in CI.
• fe publish my-feature — upload source and register the new version.
• fe link my-feature toolkit/store — wire up a local toolkit dependency.

What your platform team provides

You do not need to understand how the platform works to ship features. Your platform team provides:

Day-to-day workflow

A typical feature cycle looks like this:

1. Scaffold once: fe new acme/my-feature creates my-feature/ with a render() stub.
2. Develop: fe dev my-feature then open the shell with a sessionStorage override pointing at your dev URL.
3. Type-check in CI: fe check my-feature runs on every push.
4. Publish when ready: fe publish my-feature uploads source and prints the new version.
5. Update the route in platform.json from fe(acme/my-feature)@old to @new.

Steps 4 and 5 are independent of every other team. No build pipeline coordination. No monorepo deployment lock. Old versions stay live at their original URLs until the route is changed.

Testing against the production shell

The devtools overlay (accessible via the platform team) lets you redirect any fe(scope/name) specifier to a local fe dev URL. Overrides live in sessionStorage and affect only your current tab. No redeployment, no asking anyone for access.

// manual sessionStorage override (without devtools)
sessionStorage.setItem(
  "fe:override:fe(acme/my-feature)",
  "http://localhost:3001/"
);
// then reload — the production shell loads your local build

The devtools share button encodes active overrides as URL parameters. Send the link to a colleague and they open the same environment in their browser.

What your MFE exports

A MFE is a plain ES module and can export whatever its purpose calls for: functions, a store instance, an API client, a collection of utilities. No particular shape is required by the platform.

The exception is when your MFE is listed under routes in platform.json. In that case the runtime calls render() on navigation to mount your UI, so you must export it:

export function render(
  container: HTMLElement,
  props: Record<string, unknown>
): () => void {
  // mount your UI into container
  // return cleanup: remove your DOM, stop timers, unsubscribe listeners
}

The runtime calls render on mount and the returned function on unmount. Any framework satisfies this contract without adaptation.

Using toolkit packages

Toolkit packages are resolved at runtime through import maps. Declare them in devDependencies:

// package.json
{
  "name": "fe(acme/my-feature)",
  "devDependencies": {
    "fe(acme/store)": "^1.0.0",
    "fe(acme/network)": "^1.0.0"
  }
}

// src/index.ts
import { createStore } from "fe(acme/store)";

const count = createStore("my-feature:count", 0);

export function render(container, props) {
  // ...
  return () => {};
}

◆ Tutorials

Each tutorial builds on the previous one. Start with hello world to verify your setup, then progress to multi-team composition and toolkit integration.

1 · Hello world: one MFE, one shell

The shortest path to a running platform. By the end you will have one MFE mounting in a shell via fe serve.

bun add -d @fe/cli @fe/jit-plugin-react

# scaffold the MFE
fe new acme/hello

# scaffold the shell (or use sandbox/host-app as a template)
# edit configs/fe.config.json and configs/platform.json

fe publish hello
# add route "/" : "fe(acme/hello)@1.0.0" to platform.json
fe build shell
fe serve

Open http://localhost:3000. You should see your render() function mount into the shell container. Source: sandbox/.

2 · Two teams, one shell

Add a second MFE that imports a component from the first. This demonstrates cross-team dependency resolution through import maps.

fe new acme/mfe-a   # React MFE, no deps
fe new acme/mfe-b   # Solid.js MFE, depends on mfe-a

fe link mfe-b mfe-a  # adds mfe-a as devDependency of mfe-b

fe publish mfe-a
fe publish mfe-b

In mfe-b/src/index.ts, import from fe(acme/mfe-a). The runtime will resolve both specifiers via the injected import map. The JIT server compiles each independently using the appropriate JIT plugin.

Source: sandbox/mfe-a and sandbox/mfe-b.

3 · Using toolkit/store across MFEs

Share state between two MFEs without prop drilling or a global window variable. fe(acme/store) provides a typed pub/sub store that persists across MFE mounts and unmounts.

// in both mfe-a and mfe-b package.json
"devDependencies": { "fe(acme/store)": "^1.0.0" }

// mfe-a/src/index.ts
import { createStore } from "fe(acme/store)";

const counter = createStore("app:counter", 0);

export function render(container, props) {
  const btn = document.createElement("button");
  btn.textContent = "increment";
  btn.onclick = () => counter.set(counter.get() + 1);
  container.appendChild(btn);
  return () => container.removeChild(btn);
}

// mfe-b/src/index.ts
import { createStore } from "fe(acme/store)";

const counter = createStore("app:counter", 0);

export function render(container, props) {
  const span = document.createElement("span");
  const unsub = counter.subscribe(v => { span.textContent = String(v); });
  container.appendChild(span);
  return () => { unsub(); container.removeChild(span); };
}

Both MFEs resolve to the same fe(acme/store) version through the import map. The store instance is shared because the module is loaded once.

4 · Adding a JIT plugin for a custom JSX transform

If you need a JSX transform that is not covered by the built-in React and Solid.js plugins, you can write your own:

// @acme/fe-jit-plugin-preact/src/index.ts
import type { JitPlugin } from "@fe/core";

export default {
  name: "acme-preact",
  "build:options"(options) {
    return {
      ...options,
      jsx: "automatic",
      jsxImportSource: "preact",
    };
  },
} satisfies JitPlugin;

// configs/fe.config.json
{ "jitPlugins": ["@acme/fe-jit-plugin-preact"] }

The build:options hook receives Bun.BuildOptions and returns a modified copy. Plugins run in declaration order; later plugins can override earlier settings. The platform team declares the plugin on the server; MFE teams do not need to configure anything.