Skip to content

README.md

Latest commit

 

History

History
146 lines (106 loc) · 5.89 KB

README.md

File metadata and controls

146 lines (106 loc) · 5.89 KB
Raw

@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.

Documentation

Topic Description
Configure HTTP Clients Named clients from app config, service discovery, and explicit registration, plus resolution priority
Enable Bookmarks Registering the bookmark module via enableBookmark
Testing The /mock entry point: mockAppModules, AppMockConfigurator, and enableAppManifestMock

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).
mockAppModules Runs the real module pipeline against deterministic fakes for tests (import from @equinor/fusion-framework-app/mock).

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
@equinor/fusion-framework-app/mock mockAppModules, AppMockConfigurator, enableAppManifestMock

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

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