@equinor/fusion-framework

Bootstrap and configure the core Fusion Framework module graph — authentication, HTTP, service discovery, context, telemetry, and more — in a single initialization call.

What is this package?

@equinor/fusion-framework is the top-level entry point for starting a Fusion Framework instance. It bundles the built-in module set (MSAL auth, HTTP client factory, service discovery, services, context, event bus, and telemetry) behind a single FrameworkConfigurator / init API so consumers do not have to wire each module individually.

Use this package when you are building a portal shell, a standalone application host, or any runtime that needs the full Fusion module stack. Micro-frontend applications that run inside an already-initialized portal typically use @equinor/fusion-framework-react-app instead.

Quick start

import { FrameworkConfigurator, init } from '@equinor/fusion-framework';

// 1. Create a configurator
const configurator = new FrameworkConfigurator();

// 2. Set up authentication (MSAL)
configurator.configureMsal({
  clientId: '<your-client-id>',
  authority: 'https://login.microsoftonline.com/<your-tenant-id>',
});

// 3. Point service discovery at your registry
configurator.configureServiceDiscovery({
  client: { baseUri: 'https://service-registry.example.com' },
});

// 4. Bootstrap — resolves all modules and assigns window.Fusion
const fusion = await init(configurator);
console.log(fusion.modules); // fully initialized module instances

Key concepts

API surface

Common patterns

Configure a named HTTP client

configurator.configureHttpClient('my-api', {
  baseUri: 'https://api.example.com',
  defaultHeaders: { 'X-Custom': 'value' },
});

Optional authentication

// Pass `false` as second argument to make auth optional
configurator.configureMsal(msalConfig, false);

Extend with custom modules

import { FrameworkConfigurator, init } from '@equinor/fusion-framework';
import myCustomModule from './my-custom-module';

const configurator = new FrameworkConfigurator<[typeof myCustomModule]>();
configurator.addConfig({ module: myCustomModule, configure: (b) => { /* … */ } });
const fusion = await init(configurator);

Diagnose HTTP transport failures

FrameworkConfigurator instruments the framework's HTTP clients with createHttpTelemetry from @equinor/fusion-framework-module-telemetry/integrations. Each actual fetch attempt produces one fusion.http.request.duration metric with a success, failure (rejected fetch or non-2xx response) or cancelled (aborted signal) outcome, and a failed attempt adds one sanitized fusion.http.request.failure. URLs, headers, bodies, tokens and original errors are never recorded.

The middleware is appended after every configuration callback, so retry middleware you register wraps it and every retry is its own attempt. Timing ends when fetch resolves, not when a streamed body finishes. Token acquisition is reported separately by the auth module, and service discovery by its own records. Telemetry is connected after initialization, so requests made while modules initialize are not recorded. Exporter requests marked with markTelemetryExportRequest are excluded, and a client configured with its own middlewareHandler is not instrumented. No exporter is created.

// Opt out of framework HTTP diagnostics; other operational telemetry is unchanged.
const configurator = new FrameworkConfigurator({ httpTelemetry: false });

App modules configure their own HTTP module, which this setting does not instrument.

Built-in modules

The framework ships with the following modules enabled by default:

• @equinor/fusion-framework-module-event — cross-module event bus
• @equinor/fusion-framework-module-msal — MSAL / Azure AD authentication
• @equinor/fusion-framework-module-http — HTTP client factory and named clients
• @equinor/fusion-framework-module-service-discovery — runtime service endpoint resolution
• @equinor/fusion-framework-module-services — typed service clients
• @equinor/fusion-framework-module-context — application / project context selection
• @equinor/fusion-framework-module-telemetry — telemetry, logging, and metadata

Testing

Import from @equinor/fusion-framework/mock to initialize the framework in a test without credentials, without network access and without configuration.

import { createMockToken, mockFramework } from '@equinor/fusion-framework/mock';

const fusion = await mockFramework((configurator) => {
  configurator.msal.setAcquireToken(({ clientId, scopes }) =>
    createMockToken({
      aud: clientId,
      scp: scopes.join(' '),
      name: 'Ada Lovelace',
      preferred_username: '[email protected]',
      oid: 'ada-lovelace',
    }),
  );
  configurator.serviceDiscovery.setBaseUri('http://localhost:6669');
});

const token = await fusion.modules.auth.acquireAccessToken();
const apps = await fusion.modules.serviceDiscovery.resolveService('apps');

The real configure → initialize pipeline runs with the real built-in modules; only the boundaries that leave the process — the MSAL client and the service discovery client — are substituted. Module wiring, configuration validation and lifecycle hooks therefore behave as they do in production, so a test still catches wiring mistakes.

The entry point has no test-runner dependency, and ships no mocking API of its own — spying on an individual call is your test runner's job.

Documentation

Further reading

📚 Full documentation