@equinor/fusion-framework-module-app

Framework module for loading, configuring, and managing Fusion applications at runtime.

Primarily used by portal hosts and other framework initiators that need to discover, load, and switch between applications dynamically. The module handles manifest fetching, build resolution, configuration loading, per-user app settings, and script import of application bundles.

When to Use

• You are building a portal or shell that hosts multiple Fusion applications.
• You need to fetch application manifests and configurations from the Fusion app service.
• You need to dynamically import an application's JavaScript bundle at runtime.
• You need to read or write per-user application settings.

[!NOTE] By design this module only allows one active application at a time (currentApp). If you need multiple concurrent app instances, use the Widgets module instead.

Quick Start

Enable the module in your framework configurator:

import { enableAppModule } from '@equinor/fusion-framework-module-app';

export const configure = async (configurator: FrameworkConfigurator) => {
  enableAppModule(configurator);
};

Once enabled, the AppModuleProvider is available on the framework instance:

const appProvider = framework.modules.app;

// Set the current application by key
appProvider.setCurrentApp('my-app');

// React to current app changes
appProvider.current$.subscribe((app) => {
  if (app) {
    console.log('Current app:', app.appKey);
  }
});

Core Concepts

AppModuleProvider

The main runtime entry point. Provides methods to:

• Fetch manifests – getAppManifest(appKey) and getAppManifests() return observable streams of AppManifest objects.
• Fetch configuration – getAppConfig(appKey) returns the app's environment and endpoint configuration.
• Manage settings – getAppSettings(appKey) and updateAppSettings(appKey, settings) read and write per-user settings.
• Set/clear current app – setCurrentApp(appKey) creates an App instance and emits it on current$. clearCurrentApp() disposes the current app.

App

Represents a single loaded application. Manages internal state for the manifest, config, settings, and imported script module via a reactive state machine (FlowSubject). Key observables:

Call app.initialize() to load manifest, config, and script in parallel and receive them as a combined observable.

AppClient

Low-level HTTP client that communicates with the Fusion app service API. Handles caching (via Query), response parsing (via Zod schemas), and error mapping to typed error classes (AppManifestError, AppConfigError, AppBuildError, AppSettingsError).

AppConfig

Immutable, deeply frozen configuration object with environment (arbitrary key-value data) and endpoints (named URLs with OAuth scopes). Use config.getEndpoint('api') to retrieve a specific endpoint.

AppConfigurator

Configuration builder used during module initialization. Allows overriding the default HTTP client and asset URI:

enableAppModule(configurator, (builder) => {
  builder.setClient(async (args) => {
    const http = await args.requireInstance('http');
    return new AppClient(http.createClient('my-custom-apps'));
  });
  builder.setAssetUri('/custom-proxy');
});

Events

When the EventModule is available, the app module dispatches lifecycle events on manifest, config, settings, and script loading. Key events include:

• onCurrentAppChanged – fired when setCurrentApp or clearCurrentApp is called
• onAppManifestLoad / onAppManifestLoaded / onAppManifestFailure
• onAppConfigLoad / onAppConfigLoaded / onAppConfigFailure
• onAppSettingsLoad / onAppSettingsLoaded / onAppSettingsFailure
• onAppScriptLoad / onAppScriptLoaded / onAppScriptFailure
• onAppInitialize / onAppInitialized / onAppInitializeFailure
• onAppDispose

Error Handling

All API requests map HTTP status codes to typed error classes:

Each error includes a type property ('not_found', 'unauthorized', 'deleted', or 'unknown') for programmatic handling.

Operational telemetry

The provider implements TelemetryConnectable and obtains its shared handle through telemetry.scope('app'), with a lazy factory fallback for older custom providers. Each app owns a child scope; stage observers stay local, while timing, safe identity and disposal use the shared telemetry implementation.

When the host registers telemetry, every app reports one fusion.app.<stage>.duration outcome per attempted stage: load-manifest, load-config, load-settings, update-settings, import, load, and unload when the app is replaced or cleared. load is the outcome of each initialize() subscription: its result, its error, or cancelled when the caller unsubscribes first. Outcomes are success, failure (plus one sanitized .failure exception; stage failures carry a static reason such as not-found) or cancelled (reason superseded, unloaded, or disposed when the app module is disposed). A teardown that throws records a failed unload. Records carry only the validated appKey and appVersion; manifests, configuration, settings, URLs and error messages are never exported. A replaced app stops load reporting immediately, even while asynchronous module teardown is pending; its separately owned unload measurement finishes when teardown settles. Queued stage outcomes stay correlated with the request that produced them, not a newer request for the same stage.

Telemetry is connected after initialization and is never awaited, so loading results, errors and cancellation are unchanged. Exclude these records with a telemetry adapter or relay filter on diagnostic.module === 'app'. See Operational telemetry.

Testing

Import from @equinor/fusion-framework-module-app/mock to serve one app's manifest and config locally instead of contacting the app service. The real AppClient still backs every other request — other app keys, tagged requests, builds, settings — so pointing setClient at a different http client or service discovery registry keeps working unchanged.

import { MockAppClient } from '@equinor/fusion-framework-module-app/mock';

enableAppModule(configurator, (builder) => {
  builder.setClient(async ({ requireInstance }) => {
    const http = await requireInstance('http');
    return new MockAppClient(http.createClient('apps'), manifest, config);
  });
});

getAppManifest only resolves locally for manifest.appKey with no tag at all. getAppConfig resolves for manifest.appKey when tag is either absent or equal to the manifest's own build.version — the same tag App requests when loading config for the manifest it already resolved. Any other app key, tag, or the wrong request falls through to the real client.

[!NOTE] @equinor/fusion-framework-app/mock's mockAppModules builds on top of this class and is usually the simpler entry point for testing an application — see its Testing guide.

Main Exports