@appshell/loader 1.0.0-alpha.14 → 1.0.0-alpha.16

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.16](https://github.com/appshellhq/appshell/compare/v1.0.0-alpha.14...v1.0.0-alpha.16) (2026-08-27)
+
+### Features
+
+- deliver package vars through a shared runtime, not a global ([9473f62](https://github.com/appshellhq/appshell/commit/9473f6204b75885cd55b12a9ec71a44a74d6aa41))
+- rename core vocabulary to Package / Application / Remote ([418b7e0](https://github.com/appshellhq/appshell/commit/418b7e010b6caa1af661f7fd9c05e751e69315a9))
+
 # [1.0.0-alpha.14](https://github.com/appshell-org/appshell/compare/v1.0.0-alpha.13...v1.0.0-alpha.14) (2026-08-23)
 
 **Note:** Version bump only for package @appshell/loader

package/README.md

@@ -20,60 +20,58 @@ Working examples can be found [here](https://github.com/navaris/appshell/tree/ma
 To begin, you'll need to install `@appshell/loader`:
 
 ```console
-npm install @appshell/loader --save-dev
+npm install @appshell/loader
 ```
 
 or
 
 ```console
-yarn add -D @appshell/loader
+yarn add @appshell/loader
 ```
 
 or
 
 ```console
-pnpm add -D @appshell/loader
+pnpm add @appshell/loader
 ```
 
-The default export from this package is the loader function. It is given the global appshell configuration, and returns an async function that can be called to dynamically load Appshell components.
+The default export is the loader factory. It returns an async function that resolves a remote
+key and loads the component behind it. It needs no configuration — the composition is read
+from the document the registry served.
 
 ```ts
 import componentLoader from '@appshell/loader';
 
-const load = componentLoader(config);
+const load = componentLoader();
 
 const Component = load<MyComponent>('MyModule/MyComponent');
 
 render(<Component />);
 ```
 
-**Where does the global appshell configuration come from?**
+**Where does the composition come from?**
 
-> See [@appshell/cli](https://www.npmjs.com/package/@appshell/cli)
-
-```bash
-appshell generate global-config --registry appshell_registry_path
-```
+> The registry inlines it into the document it serves, as `window.__appshell_config__`.
 
 ## How a remote is resolved
 
 The loader walks a chain of resolvers and uses the first one that answers:
 
-| Resolver                 | Source                                                | When it answers                                                            |
-| ------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------------- |
-| `inlineResolver`         | `window.__appshell_config__`                          | The registry served the page and inlined the composition. No network call. |
-| `registryResolver`       | `GET /v1/environments/:id/remotes/:key`               | The remote was activated after this page was served.                       |
-| `legacyManifestResolver` | `index[key]` → the app's own `appshell.manifest.json` | Pre-registry hosts.                                                        |
+| Resolver           | Source                                    | When it answers                                                            |
+| ------------------ | ----------------------------------------- | -------------------------------------------------------------------------- |
+| `inlineResolver`   | `window.__appshell_config__`              | The registry served the page and inlined the composition. No network call. |
+| `registryResolver` | `GET /v1/applications/:id/remotes/:key`   | The remote was activated after this page was served.                       |
 
-Environment variables reach `window.__appshell_env__<scope>` already merged with the
-environment's overrides when a composition is present, because the registry does that
-merge server side. The legacy resolver still merges in the browser, since in that mode
-no server has.
+A package's vars are delivered into the `@appshell/runtime` store immediately before
+its remote is loaded, so they are in place before the package's modules evaluate. They
+arrive already merged with the application's overrides, because the registry does that
+merge server side — the browser applies nothing. The package reads them with `getVars()`
+from [`@appshell/vars`](../vars/README.md).
 
 You can bypass the chain entirely, which is mainly useful for tests and embedders:
 
 ```ts
-const load = componentLoader(config, { resolver: myResolver });
+const load = componentLoader({ resolver: myResolver });
 ```
 
 **Do you have any framework specific loaders?**

package/__tests__/remoteLoader.spec.ts

@@ -1,5 +1,6 @@
 /** @jest-environment jsdom */
-import { AppshellGlobalConfig, AppshellManifest } from '@appshell/config';
+import { AppshellComposition, AppshellRemote } from '@appshell/config';
+import { hasVars, readVars, resetVars } from '@appshell/runtime';
 import fetch, { enableFetchMocks } from 'jest-fetch-mock';
 import * as loadAppshellComponent from '../src/loadAppshellComponent';
 import remoteLoader from '../src/remoteLoader';
@@ -9,112 +10,107 @@ enableFetchMocks();
 jest.mock('../src/loadAppshellComponent');
 
 describe('remoteLoader', () => {
-  const manifest: AppshellManifest = {
-    remotes: {
-      'TestModule/TestComponent': {
-        id: 'test-component',
-        scope: 'TestModule',
-        module: './TestComponent',
-        manifestUrl: 'http://test.com/appshell.manifest.json',
-        remoteEntryUrl: 'http://test.com/remoteEntry.js',
-        metadata: {},
-      },
-    },
-    modules: {},
-    environment: {
-      TestModule: {
-        ENV_VAR_A: 'Original value for A',
-      },
-    },
-  };
-  const config: AppshellGlobalConfig = {
-    index: {
-      'TestModule/TestComponent': 'http://test.com/appshell.manifest.json',
-    },
+  const KEY = 'TestModule/TestComponent';
+
+  const remote: AppshellRemote = {
+    id: 'test-component',
+    scope: 'TestModule',
+    module: './TestComponent',
+    manifestUrl: 'http://test.com/appshell.manifest.json',
+    remoteEntryUrl: 'http://test.com/remoteEntry.js',
     metadata: {},
-    overrides: {
-      environment: {
-        TestModule: {
-          ENV_VAR_A: 'New value for A',
-        },
-      },
-    },
+  };
+
+  const composition: AppshellComposition = {
+    applicationId: 'acme/dev',
+    revision: 1,
+    root: KEY,
+    rootProps: {},
+    index: { [KEY]: remote.manifestUrl },
+    remotes: { [KEY]: remote },
+    vars: { TestModule: { ENV_VAR_A: 'Composed value for A' } },
   };
 
   beforeEach(() => {
-    fetch.mockIf('http://test.com/appshell.manifest.json', () =>
-      Promise.resolve({ ok: true, body: JSON.stringify(manifest) }),
-    );
+    fetch.resetMocks();
+    // The store is a singleton for the life of the page; each test gets a fresh one.
+    resetVars();
   });
 
-  it('should return the Appshell component if it is found in the registry', async () => {
+  it('should return the remote from the inlined composition without fetching', async () => {
     const ExpectedComponent = () => 'test component';
-    jest
-      .spyOn(loadAppshellComponent, 'default')
-      .mockResolvedValue(Promise.resolve(ExpectedComponent));
+    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(ExpectedComponent);
 
-    const loadRemote = remoteLoader(config);
-    const [ActualComponent, actualManifest] = await loadRemote('TestModule/TestComponent');
+    const loadRemote = remoteLoader({ composition });
+    const [ActualComponent, actualRemote] = await loadRemote(KEY);
 
+    expect(fetch).not.toHaveBeenCalled();
     expect(ActualComponent).toEqual(ExpectedComponent);
-    expect(actualManifest).toEqual(manifest);
+    expect(actualRemote).toEqual(remote);
   });
 
-  it('should apply overridden environment values', async () => {
-    const ExpectedComponent = () => 'test component';
-    jest
-      .spyOn(loadAppshellComponent, 'default')
-      .mockResolvedValue(Promise.resolve(ExpectedComponent));
+  it('should hand the composed vars to the remote', async () => {
+    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(() => 'test component');
 
-    const loadRemote = remoteLoader(config);
+    await remoteLoader({ composition })(KEY);
 
-    await loadRemote('TestModule/TestComponent');
+    expect(readVars('TestModule')).toEqual({ ENV_VAR_A: 'Composed value for A' });
+  });
+
+  it('should deliver the vars before the remote is given a chance to evaluate', async () => {
+    const order: string[] = [];
+    jest.spyOn(loadAppshellComponent, 'default').mockImplementation(async () => {
+      order.push(hasVars('TestModule') ? 'vars delivered' : 'vars missing');
+
+      return () => 'test component';
+    });
 
-    // eslint-disable-next-line no-underscore-dangle
-    expect(window.__appshell_env__TestModule).toMatchObject({ ENV_VAR_A: 'New value for A' });
+    await remoteLoader({ composition })(KEY);
+
+    expect(order).toEqual(['vars delivered']);
   });
 
-  it('should throw if remote key is not found in the registry', async () => {
-    const ExpectedComponent = () => 'test component';
-    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(ExpectedComponent);
+  it('should leave nothing on the window', async () => {
+    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(() => 'test component');
 
-    const loadRemote = remoteLoader(config);
+    await remoteLoader({ composition })(KEY);
 
-    await expect(loadRemote('TestModule/DoesNotExist')).rejects.toThrow(
-      /Remote resource not found in registry/i,
-    );
+    expect(Object.keys(window).filter((key) => key.startsWith('__appshell_vars__'))).toEqual([]);
   });
 
-  it('should throw if load Appshell component fails', async () => {
-    jest.spyOn(loadAppshellComponent, 'default').mockRejectedValue(new Error('failed'));
+  it('should fall back to the registry for a remote activated after the page was served', async () => {
+    const added: AppshellRemote = { ...remote, scope: 'LateModule', module: './Late' };
+    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(() => 'late component');
+    fetch.mockResponseOnce(JSON.stringify(added));
 
-    const loadRemote = remoteLoader(config);
+    const [, actualRemote] = await remoteLoader({ composition })('LateModule/Late');
 
-    await expect(loadRemote('TestModule/TestComponent')).rejects.toThrow(
-      /Failed to load component/i,
+    expect(fetch).toHaveBeenCalledWith(
+      '/v1/applications/acme/dev/remotes/LateModule/Late',
+      expect.anything(),
     );
+    expect(actualRemote).toEqual(added);
   });
 
-  it('should load from an inlined composition without fetching a manifest', async () => {
-    const ExpectedComponent = () => 'test component';
-    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(ExpectedComponent);
-    fetch.resetMocks();
+  it('should throw when neither the composition nor the registry has the remote', async () => {
+    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(() => 'test component');
+    fetch.mockResponseOnce('', { status: 404 });
 
-    const loadRemote = remoteLoader(config, {
-      composition: {
-        environmentId: 'acme/dev',
-        revision: 1,
-        index: config.index,
-        remotes: manifest.remotes,
-        environment: { TestModule: { ENV_VAR_A: 'Composed value for A' } },
-      },
-    });
-    const [ActualComponent, actualManifest] = await loadRemote('TestModule/TestComponent');
+    await expect(remoteLoader({ composition })('TestModule/DoesNotExist')).rejects.toThrow(
+      /Remote resource not found in registry/i,
+    );
+  });
+
+  it('should throw when there is no composition at all', async () => {
+    jest.spyOn(loadAppshellComponent, 'default').mockResolvedValue(() => 'test component');
 
+    await expect(remoteLoader()(KEY)).rejects.toThrow(/Remote resource not found in registry/i);
     expect(fetch).not.toHaveBeenCalled();
-    expect(ActualComponent).toEqual(ExpectedComponent);
-    expect(actualManifest?.modules).toEqual({});
-    // eslint-disable-next-line no-underscore-dangle
-    expect(window.__appshell_env__TestModule).toEqual({ ENV_VAR_A: 'Composed value for A' });
+  });
+
+  it('should throw if loading the Appshell component fails', async () => {
+    jest.spyOn(loadAppshellComponent, 'default').mockRejectedValue(new Error('failed'));
+
+    await expect(remoteLoader({ composition })(KEY)).rejects.toThrow(/Failed to load component/i);
   });
 });

package/__tests__/resolvers.spec.ts

@@ -1,12 +1,7 @@
 /** @jest-environment jsdom */
-import { AppshellComposition, AppshellGlobalConfig, AppshellManifest } from '@appshell/config';
+import { AppshellComposition, AppshellManifest } from '@appshell/config';
 import fetch, { enableFetchMocks } from 'jest-fetch-mock';
-import {
-  chainResolvers,
-  inlineResolver,
-  legacyManifestResolver,
-  registryResolver,
-} from '../src/resolvers';
+import { chainResolvers, inlineResolver, registryResolver } from '../src/resolvers';
 
 enableFetchMocks();
 
@@ -25,17 +20,17 @@ const manifest: AppshellManifest = {
     },
   },
   modules: { TestModule: { name: 'TestModule' } },
-  environment: { TestModule: { ENV_VAR_A: 'Original value for A' } },
+  vars: { TestModule: { ENV_VAR_A: 'Original value for A' } },
 };
 
-const config: AppshellGlobalConfig = { index: { [KEY]: MANIFEST_URL } };
-
 const composition: AppshellComposition = {
-  environmentId: 'acme/dev',
+  applicationId: 'acme/dev',
   revision: 7,
-  index: config.index,
+  root: KEY,
+  rootProps: {},
+  index: { [KEY]: MANIFEST_URL },
   remotes: manifest.remotes,
-  environment: manifest.environment,
+  vars: manifest.vars,
 };
 
 beforeEach(() => {
@@ -48,47 +43,13 @@ describe('inlineResolver', () => {
 
     expect(fetch).not.toHaveBeenCalled();
     expect(resolution?.remote).toEqual(manifest.remotes[KEY]);
-    expect(resolution?.environment).toEqual({ ENV_VAR_A: 'Original value for A' });
+    expect(resolution?.vars).toEqual({ ENV_VAR_A: 'Original value for A' });
   });
 
   it('yields to the next resolver when the key is absent', async () => {
     await expect(inlineResolver(composition)('Other/Key')).resolves.toBeUndefined();
     await expect(inlineResolver(undefined)(KEY)).resolves.toBeUndefined();
   });
-
-  // Locks the claim that the synthesized manifest is a drop-in for `ManifestProvider`.
-  it('synthesizes a manifest matching the legacy one apart from modules', async () => {
-    fetch.mockResponseOnce(JSON.stringify(manifest));
-
-    const legacy = await legacyManifestResolver(config)(KEY);
-    const inline = await inlineResolver(composition)(KEY);
-
-    expect(inline?.manifest).toEqual({ ...legacy?.manifest, modules: {} });
-    expect(inline?.environment).toEqual(legacy?.environment);
-  });
-});
-
-describe('legacyManifestResolver', () => {
-  it('merges environment overrides client side, because no server did', async () => {
-    fetch.mockResponseOnce(JSON.stringify(manifest));
-
-    const resolution = await legacyManifestResolver({
-      ...config,
-      overrides: { environment: { TestModule: { ENV_VAR_A: 'New value for A' } } },
-    })(KEY);
-
-    expect(resolution?.environment).toEqual({ ENV_VAR_A: 'New value for A' });
-  });
-
-  it('fetches each manifest only once', async () => {
-    fetch.mockResponse(JSON.stringify(manifest));
-    const resolve = legacyManifestResolver(config);
-
-    await resolve(KEY);
-    await resolve(KEY);
-
-    expect(fetch).toHaveBeenCalledTimes(1);
-  });
 });
 
 describe('registryResolver', () => {
@@ -99,7 +60,7 @@ describe('registryResolver', () => {
     const resolution = await registryResolver(composition, 'http://registry')('LateModule/Late');
 
     expect(fetch).toHaveBeenCalledWith(
-      'http://registry/v1/environments/acme/dev/remotes/LateModule/Late',
+      'http://registry/v1/applications/acme/dev/remotes/LateModule/Late',
       expect.anything(),
     );
     expect(resolution?.remote).toEqual(added);