Installation

Private beta#

The @z0devs/* packages are in private beta: they're served from Zone Zero's registry to design partners while we harden for general availability, and installing them needs an access token — that's the Z0_NPM_TOKEN in every snippet below. There are two ways in:

• Try the live demo — a real federated shell loading real plugins in your browser, including the failure gallery. No install, no token.
• Request beta access — design partners get white-glove onboarding, a direct channel, and a registry token. Four questions, we reply within a day.

Already a partner? Continue below.

Registry access#

Two registries, one rule: the scaffolder is public, the runtime packages are gated.

• create-z0-plugin lives on npmjs (MIT-licensed), so pnpm create z0-plugin works with no setup at all — no token, no .npmrc, any package manager. It also writes the .npmrc below into the project it generates.
• @z0devs/* live on ZoneZero's private registry and need an access token. Point the scope at it once, per project or per machine:

@z0devs:registry=https://npm.zonezero.dev/
//npm.zonezero.dev/:_authToken=${Z0_NPM_TOKEN}

Set Z0_NPM_TOKEN in your shell (or CI secret store) before installing. It's deliberately not named NPM_TOKEN — your CI may already define that for npmjs, and a collision sends a token to the wrong registry. The scoped line covers every @z0devs/* package; nothing else about your registry configuration needs to change — in particular, don't set registry= (the default) to the private registry, or every unscoped package on earth will try to resolve through it.

Install#

pnpm add @z0devs/module-federation \
  react react-dom react-router-dom eventemitter3 react-error-boundary \
  @module-federation/runtime @tanstack/react-query

Or skip the wiring entirely and scaffold:

pnpm create z0-plugin my-plugin

Peer dependencies#

Every package declares its peers explicitly rather than bundling them — the whole point is that the host and its plugins share one copy of each.

React 19 is permitted everywhere (>=18). React Router 6 and 7 both work — the packages import through a single react-router-dom re-export seam, and that specifier resolves identically in both majors.

Bundler requirements#

The Module Federation runtime peer range spans 0.6 → 2.x; the library has been validated against @module-federation/runtime and @module-federation/enhanced 2.5.1, with consumers on 0.21.x still type-checking.

Required MF config on both sides#

Whatever bundler you use, the host and every plugin must share React as a singleton — two React copies in one tree is the single most common federation failure:

Don't write that map by hand — @z0devs/mf-config emits it, subpaths included:

import { z0Federation } from "@z0devs/mf-config";
 
new ModuleFederationPlugin(
  z0Federation({
    name: "shell",          // or your plugin's remote id
    exposes: { "./sharedStore": "./src/store/sharedStore.tsx" },
    router: true,           // also share react-router-dom
  }),
);

That expands to exactly this, which is what you'd otherwise maintain in every app:

shared: {
  react: { singleton: true, eager: true, requiredVersion: false },
  "react-dom": { singleton: true, eager: true, requiredVersion: false },
  "react-router-dom": { singleton: true, eager: true, requiredVersion: false },
  // Subpath entrypoints must be shared too — not just the package roots.
  "react/jsx-runtime": { singleton: true, eager: true, requiredVersion: false },
  "react/jsx-dev-runtime": { singleton: true, eager: true, requiredVersion: false },
  "react-dom/client": { singleton: true, eager: true, requiredVersion: false },
}

z0Federation returns plain options data, so nothing is a one-way door: spread it and override any field, or import only z0Shared() and keep the rest of your block hand-written. Add it as a devDependency — it is build-time only and never reaches a browser bundle.

The host additionally exposes its store, and each plugin declares the host as a remote:

exposes: { "./sharedStore": "./src/store/sharedStore.tsx" }

remotes: { shell: "shell@http://localhost:3400/remoteEntry.js" },
exposes: { "./init": "./src/init.tsx", "./HomePage": "./src/HomePage.tsx" }

Cross-bundler: a Vite remote under an Rspack host#

Supported and verified end to end. It needs four non-default settings on the Vite side and one you must avoid — enough detail that it has its own page: Cross-bundler.

The prerequisite is the section above: share the subpath entrypoints on every participant. An unshared react/jsx-runtime sends the Vite remote to its own React, and that is the failure most often mistaken for "Vite does not work here".

Standalone flag#

The plugin bridge decides between the real host store and the local stub by reading process.env.IS_STANDALONE, which does not exist in a browser — inline it at build time:

new DefinePlugin({
  "process.env.IS_STANDALONE": JSON.stringify(process.env["IS_STANDALONE"] ?? "false"),
});

{
  "scripts": {
    "dev": "rspack serve",
    "dev:standalone": "cross-env IS_STANDALONE=true rspack serve"
  }
}

Verify the install#

import { SHELL_API_VERSION, validateManifestEntry } from "@z0devs/mf-core";
 
console.log(SHELL_API_VERSION);                       // the host↔plugin contract version
console.log(validateManifestEntry(myManifestEntry));  // lint an entry before you ship it

Next#