@appshell/runtime 1.0.0-alpha.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Navaris Technologies, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @appshell/runtime
+
+The store that delivers a package's runtime configuration (`vars`) to it.
+
+This is a **shared singleton**. There is exactly one instance per page, held in the
+module federation share scope, and both the host and every package must declare it as
+such. It replaced `window.__appshell_vars__<scope>`.
+
+Most packages should not import this directly — use `@appshell/runtime/vars` below,
+which supplies the scope for you.
+
+## `@appshell/runtime/vars`
+
+The accessor most packages actually want. It reads *this* package's vars, with no scope
+to pass and no way to name someone else's:
+
+```ts
+import { getVars } from '@appshell/runtime/vars';
+
+const { BACKGROUND_COLOR } = getVars<{ BACKGROUND_COLOR: string }>();
+```
+
+It is a subpath rather than a main-entry export for a reason. `AppshellPlugin` compiles
+the package's own scope into whatever imports it, and the main entry is the *shared*
+module — one instance for the whole page — so a scope baked in there would be one
+package's, and every other package would read the wrong vars.
+
+The exact-match share key `'@appshell/runtime'` does not catch `'@appshell/runtime/vars'`,
+so each package bundles its own copy of the accessor with its own scope, while the store
+they all reach stays the single shared instance.
+
+`getVars` throws `MissingScopeError` when the package was built without `AppshellPlugin`,
+since nothing substituted the scope.
+
+## Contract
+
+```ts
+setVars(scope, vars); // the host, immediately before loading a remote
+readVars(scope); // a package, reading its own configuration
+hasVars(scope); // branch instead of catch
+```
+
+`@appshell/loader` calls `setVars` before it loads a remote, so a package's vars are in
+place before its modules evaluate — including a read at module-eval time.
+
+The first write for a scope wins and is frozen. Re-delivering the identical vars is a
+no-op, because the same remote can be mounted more than once; replacing them throws
+`VarsConflictError`.
+
+`readVars` throws `MissingVarsError` rather than returning an empty object. A package
+that silently renders with no configuration is the failure this replaced.
+
+## What this does and does not fix
+
+Against the global it replaced, it fixes: unbounded, never-cleaned-up keys; silent
+cross-package overwrite; the load-order coupling between host and remote; and being
+untyped and undiscoverable.
+
+It **does not make a scope's vars private.** Any code on the page can call
+`readVars('SomeOtherScope')`, and a package that loads early can squat on a scope that
+has not been delivered yet. Nothing short of a separate realm — an iframe, a worker —
+would change that, and none of this is a security boundary. Do not put a secret in
+`vars`; the registry serves them to the browser in the composition either way.
+
+## Setup
+
+Both sides declare it, or each ends up with its own empty store:
+
+```js
+new ModuleFederationPlugin({
+  shared: {
+    '@appshell/runtime': { singleton: true },
+  },
+});
+```
+
+`AppshellPlugin` fails the build when a package omits it.

package/dist/main.js

@@ -0,0 +1 @@
+!function(e,r){if("object"==typeof exports&&"object"==typeof module)module.exports=r();else if("function"==typeof define&&define.amd)define([],r);else{var t=r();for(var s in t)("object"==typeof exports?exports:e)[s]=t[s]}}(this,(()=>(()=>{"use strict";var e={d:(r,t)=>{for(var s in t)e.o(t,s)&&!e.o(r,s)&&Object.defineProperty(r,s,{enumerable:!0,get:t[s]})},o:(e,r)=>Object.prototype.hasOwnProperty.call(e,r),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},r={};e.r(r),e.d(r,{ANONYMOUS:()=>a,MissingScopeError:()=>o,MissingVarsError:()=>t,VarsConflictError:()=>s,getIdentity:()=>n,hasVars:()=>d,readVars:()=>p,resetVars:()=>l,setVars:()=>c});class t extends Error{constructor(e,r){super(`No vars were delivered for '${e}'. ${r.length?`Vars are present for ${r.map((e=>`'${e}'`)).join(", ")} — check that '${e}' matches the module federation name the registry knows this package by.`:"Nothing has delivered vars on this page — check that the host and this package both declare '@appshell/runtime' as a shared singleton."}`),this.name="MissingVarsError",this.scope=e}}class s extends Error{constructor(e){super(`Vars for '${e}' were already delivered and cannot be replaced. A scope receives its vars once per page load.`),this.name="VarsConflictError",this.scope=e}}class o extends Error{constructor(){super("Cannot tell which package this is. '@appshell/runtime/vars' needs the scope that AppshellPlugin injects at build time — add it to this package's webpack plugins, or read the store directly with readVars(scope) from '@appshell/runtime'."),this.name="MissingScopeError"}}const a={authenticated:!1},n=()=>{if("undefined"==typeof window)return a;const e=window.__appshell_identity__;return(e=>{if("object"!=typeof e||null===e)return!1;const r=e;return!1===r.authenticated||!0===r.authenticated&&"string"==typeof r.subject&&"string"==typeof r.username&&Array.isArray(r.roles)})(e)?e:a},i=new Map,c=(e,r)=>{const t=i.get(e);var o,a;if(t){if(o=t,a=r,![...new Set([...Object.keys(o),...Object.keys(a)])].every((e=>o[e]===a[e])))throw new s(e)}else i.set(e,Object.freeze({...r}))},p=e=>{const r=i.get(e);if(!r)throw new t(e,[...i.keys()]);return r},d=e=>i.has(e),l=()=>{i.clear()};return r})()));

package/dist/types/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A package asked for vars that were never delivered.
+ *
+ * Almost always one of three things: the package was loaded outside `remoteLoader`
+ * (a test, a storybook, a direct import), the host and the package resolved separate
+ * copies of `@appshell/runtime` because one of them failed to declare it as a
+ * singleton, or the scope compiled into the package is not the scope the registry
+ * knows it by.
+ */
+export declare class MissingVarsError extends Error {
+    readonly scope: string;
+    constructor(scope: string, known: string[]);
+}
+/**
+ * Something tried to replace vars that were already delivered for a scope.
+ *
+ * The first write wins and is final. Within one page load a scope has exactly one
+ * vars object — both resolvers read it from the same `composition.vars[scope]` — so a
+ * differing second write is a bug or a package reaching for a scope that is not its own,
+ * and neither should be applied quietly.
+ */
+export declare class VarsConflictError extends Error {
+    readonly scope: string;
+    constructor(scope: string);
+}
+/**
+ * The package was built without `AppshellPlugin`, so nothing substituted the scope the
+ * `@appshell/runtime/vars` accessor needs to know which vars are its own.
+ */
+export declare class MissingScopeError extends Error {
+    constructor();
+}

package/dist/types/identity.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Who is looking at the page, as the registry was told by the gateway.
+ *
+ * Unlike vars this is not scope-specific — there is one visitor per page, not one
+ * per package — so it lives in the main entry rather than needing the subpath
+ * trick `@appshell/runtime/vars` uses to get a per-package scope substituted.
+ *
+ * It is also not delivered through the vars store, and that is a constraint rather
+ * than a preference: `setVars` freezes on first write and throws on replacement,
+ * which is what stops one package overwriting another's configuration. Identity
+ * changes — sign-in, sign-out, token refresh — so it cannot live behind a
+ * write-once door without either breaking that guarantee or never updating.
+ */
+/**
+ * A discriminated union rather than an optional user, so `username` cannot be read
+ * without the anonymous case having been handled. The compiler enforces what a
+ * convention would only ask for.
+ */
+export type Identity = {
+    authenticated: false;
+} | {
+    authenticated: true;
+    subject: string;
+    username: string;
+    roles: string[];
+};
+export declare const ANONYMOUS: Identity;
+declare global {
+    interface Window {
+        __appshell_identity__?: unknown;
+    }
+}
+/**
+ * The visitor, or the anonymous identity when there is none.
+ *
+ * Never throws and never returns undefined — an absent or malformed value is
+ * anonymous, which is a state every caller already has to handle. That is the
+ * opposite of `readVars`, which throws when a scope is missing, and the difference
+ * is deliberate: a package with no configuration cannot do its job, while a package
+ * with no signed-in user usually can and simply renders differently.
+ *
+ * This is a typed accessor, not a boundary. The value is inlined into the document
+ * and any script on the page can read it directly, exactly as with vars. Treat it
+ * as what the server said about the visitor, never as proof of anything: it carries
+ * no token and grants nothing. Anything that matters is re-checked server-side.
+ */
+export declare const getIdentity: () => Identity;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { MissingScopeError, MissingVarsError, VarsConflictError } from './errors';
+export { ANONYMOUS, getIdentity } from './identity';
+export type { Identity } from './identity';
+export { hasVars, readVars, resetVars, setVars } from './store';
+export type { Vars } from './types';
+export type { AppshellIndex, AppshellRemote, Metadata, ModuleFederationLoader, RemoteLoader, } from './wire';

package/dist/types/store.d.ts

@@ -0,0 +1,25 @@
+import type { Vars } from './types';
+/**
+ * Delivers a scope's vars. Called by `@appshell/loader` immediately before the remote
+ * is loaded, so they are in place before the package's modules evaluate.
+ *
+ * The first write for a scope wins and is frozen. Re-delivering the identical vars is a
+ * no-op — the same remote can be mounted more than once — but replacing them throws.
+ * That is what keeps one package from overwriting another's: by the time any package
+ * evaluates, the host has already written for it.
+ *
+ * It does not make a scope's vars *private*. Any code on the page can still read another
+ * scope by name, and nothing short of a separate realm would change that.
+ */
+export declare const setVars: (scope: string, vars: Vars) => void;
+/**
+ * Reads a scope's vars, throwing rather than handing back an empty object — a package
+ * that silently renders with no configuration is the failure this replaced.
+ *
+ * Prefer `getVars()` from `@appshell/runtime/vars`, which supplies the scope for you.
+ */
+export declare const readVars: <TVars extends Vars = Vars>(scope: string) => TVars;
+/** Whether a scope has been delivered, for callers that want to branch instead of catch. */
+export declare const hasVars: (scope: string) => boolean;
+/** Test seam. Not part of the contract a package should build on. */
+export declare const resetVars: () => void;

package/dist/types/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A package's runtime configuration, already merged by the registry — a package's
+ * declared vars, then the application's `overrides.vars`.
+ *
+ * Structurally identical to `AppshellComposition['vars'][scope]` in `@appshell/config`,
+ * but declared here rather than imported. This package is a shared singleton loaded
+ * into every micro-frontend on the page, so it carries no dependencies at all.
+ */
+export type Vars = Record<string, string | number | undefined>;

package/dist/types/vars.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The scope-aware accessor, deliberately kept out of this package's main entry.
+ *
+ * `@appshell/runtime` is shared as a singleton, so exactly one copy of it exists on the
+ * page — whichever package wins the share negotiation. A `__APPSHELL_SCOPE__` compiled
+ * into that copy would be one package's scope, and every other package would silently
+ * read the wrong vars. So this module ships as the `@appshell/runtime/vars` subpath,
+ * which the exact-match share key does not catch: each package bundles its own copy and
+ * gets its own scope substituted, while the store they all reach through the bare
+ * `@appshell/runtime` import below stays the one shared instance.
+ *
+ * That bare specifier is load-bearing. A relative import of the store here would bind to
+ * a local copy and bypass the singleton entirely.
+ */
+import { type Vars } from '@appshell/runtime';
+/**
+ * This package's runtime configuration, as the registry composed it — the vars the
+ * package declared in its `appshell.config.yaml`, with the application's
+ * `overrides.vars` layered over them.
+ *
+ * Throws rather than returning an empty object when nothing was delivered. A package
+ * that renders with no configuration at all is the failure this is here to prevent.
+ *
+ * ```ts
+ * import { getVars } from '@appshell/runtime/vars';
+ *
+ * const { BACKGROUND_COLOR } = getVars<{ BACKGROUND_COLOR: string }>();
+ * ```
+ */
+export declare const getVars: <TVars extends Vars = Vars>() => TVars;
+export { MissingScopeError, MissingVarsError, type Vars } from '@appshell/runtime';

package/dist/types/wire.d.ts

@@ -0,0 +1,58 @@
+/**
+ * What the browser is told about a remote.
+ *
+ * These live here rather than in `@appshell/config` because config is build tooling — it
+ * carries yaml, lodash and axios — and a package that only wants to type a remote should
+ * not install a compiler to get it. This package is already the one every micro-frontend
+ * on the page shares, and it has no dependencies of its own to pass on.
+ *
+ * `AppshellManifest` deliberately stays in `@appshell/config`. It is a build artifact, and
+ * its `modules` field is Module Federation plugin options — build-time webpack
+ * configuration the browser never sees and this package should never drag in.
+ */
+/** Arbitrary, application-defined description of a remote. Appshell never reads it. */
+export type Metadata = Record<string, unknown>;
+/**
+ * How a host loads a remote, named as one kind among possible kinds.
+ *
+ * scope, module and shareScope are Module Federation's vocabulary, and they used to sit
+ * at the top level of a remote where nothing said so — which is what would have made a
+ * second framework awkward, not the words themselves. Nested under a kind they are
+ * exactly correct, and something like single-spa slots beside them without reinterpreting
+ * anything already published.
+ *
+ * apiVersion follows the house style set by appshell.app.yaml, and the group is appshell's
+ * because appshell owns this schema: it decides which fields it stores, even though the
+ * fields describe federation concepts. If federation ever needs a different recipe that is
+ * a v2, and manifests published under v1 keep meaning what they meant — which matters,
+ * because they are immutable and hashed.
+ */
+export type ModuleFederationLoader = {
+    apiVersion: 'federation.appshell.org/v1';
+    kind: 'ModuleFederation';
+    scope: string;
+    module: string;
+    shareScope?: string;
+    /** The entry file the build emits, conventionally remoteEntry.js. */
+    filename: string;
+    /**
+     * What built this, recorded as a fact rather than a constraint.
+     *
+     * Deliberately not a version range. A range is a claim about the environment, and a
+     * package cannot make it: it knows what built it and not what will load it, and the
+     * host is what registers the remote. Freezing one into an immutable artifact is the
+     * same mistake as freezing its origin.
+     */
+    builtWith?: string;
+};
+export type RemoteLoader = ModuleFederationLoader;
+/** A remote the registry has already resolved, so the browser needs no manifest fetch. */
+export type AppshellRemote<TMetadata = Metadata> = {
+    id: string;
+    manifestUrl: string;
+    remoteEntryUrl: string;
+    loader: RemoteLoader;
+    metadata: TMetadata;
+};
+/** Remote key to manifest url. */
+export type AppshellIndex = Record<string, string>;

package/dist/vars.js

@@ -0,0 +1 @@
+!function(e,r){if("object"==typeof exports&&"object"==typeof module)module.exports=r(require("@appshell/runtime"));else if("function"==typeof define&&define.amd)define(["@appshell/runtime"],r);else{var o="object"==typeof exports?r(require("@appshell/runtime")):r(e["@appshell/runtime"]);for(var t in o)("object"==typeof exports?exports:e)[t]=o[t]}}(this,(e=>(()=>{"use strict";var r={164(r){r.exports=e}},o={};function t(e){var n=o[e];if(void 0!==n)return n.exports;var i=o[e]={exports:{}};return r[e](i,i.exports,t),i.exports}t.n=e=>{var r=e&&e.__esModule?()=>e.default:()=>e;return t.d(r,{a:r}),r},t.d=(e,r)=>{for(var o in r)t.o(r,o)&&!t.o(e,o)&&Object.defineProperty(e,o,{enumerable:!0,get:r[o]})},t.o=(e,r)=>Object.prototype.hasOwnProperty.call(e,r),t.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var n={};t.r(n),t.d(n,{MissingScopeError:()=>i.MissingScopeError,MissingVarsError:()=>i.MissingVarsError,getVars:()=>s});var i=t(164);const s=()=>(0,i.readVars)((()=>{if("undefined"==typeof __APPSHELL_SCOPE__)throw new i.MissingScopeError;return __APPSHELL_SCOPE__})());return n})()));

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@appshell/runtime",
+  "version": "1.0.0-alpha.100",
+  "description": "The shared singleton that delivers a package's runtime configuration to it",
+  "main": "dist/main.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./vars": {
+      "types": "./dist/types/vars.d.ts",
+      "default": "./dist/vars.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "vars": [
+        "./dist/types/vars.d.ts"
+      ]
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appshellhq/appshell.git"
+  },
+  "author": "Robert Hamilton <rh@navaris.com>",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "webpack --mode production && npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "start": "webpack --watch --mode development && npm run build:types",
+    "stats": "webpack --json > stats.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "module federation",
+    "micro-frontends",
+    "appshell"
+  ],
+  "license": "MIT",
+  "gitHead": "2df8eb5b605b036d36af7e8d3ee2990bc2b63e5e"
+}