@equinor/fusion-framework-app

title: "@equinor/fusion-framework-app" description: "Application foundation package for the Fusion Framework" category: "Application" tag:

• app
• core
• foundation
• modules
• framework
• typescript

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.

Documentation

Installation

pnpm add @equinor/fusion-framework-app

Quick Start

import type { AppModuleInitiator } from '@equinor/fusion-framework-app';
import { enableState } from '@equinor/fusion-framework-app/enable-state';

const configure: AppModuleInitiator = (configurator) => {
    enableState(configurator);
};

[!CAUTION] The state management module is a powerful tool, but it's important to know the potential pitfalls and limitations when using it in your application. The state management is global and can lead to unexpected behavior if not used carefully.

example 1: If you have multiple components that rely on the same state, updating the state in one component can cause re-renders in all components that use that state, potentially leading to performance issues.

example 2: The user has open multiple tabs of the application, and each tab is modifying the same state. This can lead to unexpected behavior, as changes made in one tab will be reflected to all tabs. (like storing user preferences for selected columns)

Bookmarks

The bookmark module provides a way to save and restore the state of the application. This is useful for saving the state of the application when the user navigates away from the application and then returns to the application.

# Install the bookmark module
pnpm add @equinor/fusion-framework-module-bookmark

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

Portal authentication is inherited by default

configureModules creates an AppConfigurator that registers auth alongside event and http before the app's configuration callback runs. It initializes these modules with fusion.modules as the parent reference. MSAL then reuses the portal auth provider through its version-compatible createProxyProvider path, sharing the existing client and live account without another login. The React app bootstrap uses this same path.

Ordinary hosted apps do not need enableMSAL to use Roles V2. Register enableRoles normally; the real Roles client reads the inherited account before each account-scoped operation, so parent account changes and sign-out are reflected in subsequent requests. An unavailable account produces RequiredAccessRolesError, not a new login flow.

For deliberate custom authentication, use enableMSAL with builder.setProvider(customAuthProvider). The explicitly supplied provider remains authoritative, even when signed out. A bare enableMSAL call is redundant here, and client settings alone do not override a parent provider. This default registration is independent of telemetry and does not apply to bare ModulesConfigurator bootstraps. See the Roles authentication boundary.

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.
• configurator.configureAppIdentification(options) — control the x-fusion-app* headers that identify the app to backend telemetry. See App Identification Headers.

Sub-path Exports

Configure HTTP Clients

The AppConfigurator can register named HTTP clients from several sources — application config endpoints, service discovery, or explicit registration — and you retrieve one at runtime with framework.modules.http.createClient(name).

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

See Configure HTTP Clients for auto-registration from app.config.ts, explicit registration, and resolution priority when a client is configured in more than one place.

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 { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';

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

See Enable Bookmarks for payload generator cleanup behavior.

Testing

Import from @equinor/fusion-framework-app/mock to run an application's real module pipeline in tests — the real event/http/msal modules, the real AppConfigurator configuration pipeline, and real lifecycle — while only the boundaries that reach outside the process are substituted with deterministic fakes. This entry point has no dependency on Vitest or any other test runner.

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

const manifest = { appKey: 'my-app', displayName: 'My App', description: 'My app', type: 'standalone' } as const;
const modules = await mockAppModules(undefined, { manifest });

See Testing for AppMockConfigurator, enableAppManifestMock, and customizing the mocked parent's service discovery.

Types

Further Reading

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