@equinor/fusion-framework-app

Configuration and initialization layer for Fusion applications.

Use this package to set up application modules, configure HTTP clients, integrate with service discovery, enable bookmarks, and wire up telemetry — all with a single configureModules call.

Most Fusion apps should use @equinor/fusion-framework-react-app instead. This lower-level package is for framework-agnostic or advanced scenarios.

Installation

pnpm add @equinor/fusion-framework-app

Quick Start

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

// Create an initializer with custom configuration
const initialize = configureModules((configurator, { fusion, env }) => {
  // Register a named HTTP client
  configurator.configureHttpClient('myApi', {
    baseUri: 'https://api.example.com',
    defaultScopes: ['api://client-id/.default'],
  });
});

// Bootstrap the application
const modules = await initialize({ fusion, env });

Key Concepts

| Concept | Description | |---|---| | configureModules | Factory function that creates an async initializer for application modules. | | AppConfigurator | Internal configurator created by configureModules; registers default modules (event, http, msal) and reads endpoint config. | | IAppConfigurator | Public interface for the configurator, used when typing configuration callbacks. | | AppModuleInitiator | Callback signature accepted by configureModules for user-supplied setup. | | AppEnv | Environment descriptor containing the app manifest, config, and optional basename. | | enableBookmark | Helper to enable the bookmark module (import from @equinor/fusion-framework-app/enable-bookmark). |

API Surface

configureModules(cb?)

Returns an async initializer (args: { fusion, env }) => Promise<AppModulesInstance>.

The optional callback receives an IAppConfigurator and the Fusion/env args, giving you access to:

• configurator.configureHttpClient(name, options) — register a named HTTP client with explicit base URI and scopes.
• configurator.configureHttp(...) — low-level HTTP module configuration.
• configurator.useFrameworkServiceClient(serviceName, options?) — register a client resolved via Fusion service discovery.

Sub-path Exports

| Export path | What it provides | |---|---| | @equinor/fusion-framework-app | configureModules, AppConfigurator, IAppConfigurator, all type aliases | | @equinor/fusion-framework-app/enable-bookmark | enableBookmark function |

Configure HTTP Clients

The AppConfigurator can register named HTTP clients from several sources. You retrieve a client at runtime with framework.modules.http.createClient(name).

From Application Config (auto-registration)

Endpoints defined in app.config.<env>.ts are automatically registered as named HTTP clients when the AppConfigurator is created — no extra code needed in config.ts.

// app.config.ts
import { defineAppConfig } from '@equinor/fusion-framework-cli/app';

export default defineAppConfig(() => ({
  endpoints: {
    schedule: {
      url: 'https://schedule-api.example.com',
      scopes: ['api://schedule-id/.default'],
    },
  },
}));

After initialization, use the client directly:

const client = framework.modules.http.createClient('schedule');
const data = await client.json('/items');

Via Service Discovery

const initialize = configureModules((configurator) => {
  configurator.useFrameworkServiceClient('people');
});

Explicit Registration

Use configureHttpClient in config.ts when the endpoint is not in app.config.ts, or when you need custom transport behavior such as headers, response guards, or a custom client class.

configurator.configureHttpClient('custom-api', {
  baseUri: 'https://custom.api.example.com',
  defaultScopes: ['api://custom-id/.default'],
  onCreate: (client) => {
    client.requestHandler.setHeader('X-Source', 'portal');
  },
});

Resolution Priority

When the same client name is configured in more than one place, the highest-priority source wins:

| Priority | Source | Example | |----------|--------|---------| | 1 (highest) | Session overrides | User-specific URL / scopes set at runtime via sessionStorage | | 2 | Application config endpoints | endpoints in app.config.ts | | 3 | Service-discovery registry | Resolved via useFrameworkServiceClient | | 4 (lowest) | Explicit registration | configureHttpClient(name, options) in config.ts |

This means an endpoint defined in app.config.ts will override a configureHttpClient call for the same name, and a session override will override both.

Enable Bookmarks

The bookmark module allows applications to save and restore application state.

Important: Import enableBookmark from the app-level package, not from @equinor/fusion-framework-module-bookmark directly.

import { configureModules } from '@equinor/fusion-framework-app';
import { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';

const initialize = configureModules((configurator) => {
  enableBookmark(configurator);
});

Payload generators registered through the bookmark module are automatically cleaned up when the module is disposed.

Types

| Type | Purpose | |---|---| | AppEnv | Environment descriptor (manifest, config, basename, props) | | AppModuleInitiator | Configuration callback signature for configureModules | | AppModuleInit | Full factory type wrapping AppModuleInitiator | | AppModuleInitArgs | Arguments passed to the returned initializer | | AppRenderFn | Render function for mounting an app into a DOM element | | AppManifest | Application manifest metadata (re-export) | | AppConfig | Environment-specific config (re-export) | | AppModules | Union of default application modules (re-export) | | AppModulesInstance | Resolved module instances after initialization (re-export) |

Further Reading

• Fusion Framework documentation
• @equinor/fusion-framework-react-app — React wrapper with hooks and providers