@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 environment's shellBundleUrl points at.

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

Choosing a bundle

Every environment 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 env 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 env 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.

Environment configuration

A registry-served shell needs none of this — the environment supplies the root remote, its props, and the page's title, colours and stylesheet, and the registry inlines them. These are the standalone fallbacks, read from the appshell.env.js that appshell generate env writes:

# Public url. Defaults to localhost
APPSHELL_PUBLIC_URL=
# Port the bundle's development server listens on
APPSHELL_PORT=3030
# Remote module to mount at the root, when no composition is inlined
APPSHELL_ROOT=ContainerModule/App
# Props for that remote, as a serialized JSON string
APPSHELL_ROOT_PROPS='{"foo":"bar"}'
# File to setup the environment. Defaults to .env
APPSHELL_ENV=.env
# Prefix used to specify which env vars to include when generating appshell.env.js. Leaving this empty will include ALL variables in the .env
APPSHELL_ENV_PREFIX=APPSHELL_
# Name of global variable used in the generated appshell.env.js. Defaults to window.__appshell_env__
APPSHELL_ENV_GLOBAL_VAR=__appshell_env__
# Background color of splash screen
APPSHELL_THEME_COLOR=
# Color of splash screen loading
APPSHELL_PRIMARY_COLOR=