@appshell/react-shell 1.0.0-alpha.8 → 1.0.0-alpha.80

package/README.md

@@ -17,19 +17,19 @@ Working examples can be found [here](https://github.com/appshell-org/appshell/tr
 
 `@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.
+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 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.
+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 environment resolves a shell bundle. By default that is the one the registry image ships, so
+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:
 
 ```bash
-appshell env create my-env --shell-bundle-url https://cdn.example.com/appshell/1.2.3/main.js
+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
@@ -48,36 +48,43 @@ resolved by the browser, so a shared registry can point at your machine.
 
 ```bash
 npm start
-appshell env create shell-dev --ephemeral --shell-bundle-url http://localhost:3030/main.js
+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.
 
-## Environment configuration
+## Application 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:
+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:
 
 ```sh
-# 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=
+# 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.