@appshell/react-shell

Appshell React shell for building micro-frontends with Appshell and Webpack Module federation.

Working examples can be found here.

@appshell/react-shell is the browser bundle that mounts your micro-frontends. It is not a server — the Appshell registry renders the shell document, inlines the resolved composition, and serves this bundle at the URL an application's shellBundleUrl points at.

Building a micro-frontend? You do not need this package. Run your own dev server and publish to an application; the registry loads the shell bundle for you. This README is for pinning which bundle an application uses, and for working on the bundle itself.

Choosing a bundle

Every application resolves a shell bundle. By default that is the one the registry image ships, so there is nothing to configure. Point shellBundleUrl elsewhere to pin a version or serve from a CDN:

appshell app create my-env --shell-bundle-url https://cdn.example.com/appshell/1.2.3/main.js

The package publishes dist/ and nothing else, so a registry image can serve it under a versioned path and pinning becomes an ordinary dependency bump:

RUN npm install @appshell/[email protected]
RUN cp -R node_modules/@appshell/react-shell/dist public/shell

Working on the bundle

npm start serves main.js and nothing else — the registry still renders the shell, so you develop against the same path a deployment takes. The registry does not need to be local: shellBundleUrl is resolved by the browser, so a shared registry can point at your machine.

npm start
appshell app create shell-dev --ephemeral --shell-bundle-url http://localhost:3030/main.js

Note Chrome and Firefox treat localhost as a trustworthy origin, so an https registry may load an http bundle from it. Safari is stricter — run the registry locally, or serve main.js over TLS.

Application configuration

The registry supplies the root remote, its props, and the page's title, colours, favicon and stylesheet, inlining them into the document it serves. None of it comes from this package's environment any more.

What remains here is dev-server and CLI configuration:

# Port the bundle's development server listens on
APPSHELL_PORT=3030
# Registry to publish and activate against
APPSHELL_REGISTRY=
# Credential for that registry
APPSHELL_API_KEY=

What fills the page before the root remote mounts

Nothing, currently. The shell renders no fallback: what covers the gap while the root remote is fetched is the application's business, and it cannot come from the root package itself — that package is the thing being waited for. It has to come from the document the registry renders.

The shell used to ship a Splash component for this, configured through two env vars that stopped reaching the browser when the registry took over page rendering, so it had been rendering its hardcoded fallback colours for some time. It was removed rather than rewired: a document-level splash paints on the document's first paint rather than after the shell bundle downloads, parses and mounts React, and it can be styled by the application instead of by this package.

Inner remotes are unaffected — RemoteSlot takes a fallback prop, and that has always been the consumer's to supply.