@equinor/fusion-framework-module

Core module system for Fusion Framework. This package defines the contracts, base classes, and orchestration logic that every Fusion Framework module relies on.

Use this package when you are authoring a new module or need to understand how the module lifecycle works. Application developers typically consume modules through higher-level packages such as @equinor/fusion-framework-react.

Key Concepts

Module

A Module is a plain object that declares a name, an optional configuration factory, an initialize method, and optional lifecycle hooks (postConfigure, postInitialize, dispose). Modules are the building blocks of a Fusion application.

ModulesConfigurator

ModulesConfigurator orchestrates the full module lifecycle:

1. Configure – each module's configure() factory creates a config builder; registered callbacks mutate it; postConfigure() hooks run.
2. Initialize – modules are initialized concurrently; cross-module dependencies are resolved through requireInstance().
3. Post-initialize – postInitialize() hooks and onInitialized callbacks run.
4. Plugins – registered plugins connect host-level side effects after every module is ready.

The result is a sealed ModulesInstance whose property names match the module keys and whose values are the initialized providers.

BaseConfigBuilder

An abstract class for building module configuration declaratively. Subclasses expose typed setter methods (e.g. setBaseUrl) that register callbacks. During initialization the framework collects all registered callbacks, resolves them, and merges the results into a single configuration object.

BaseModuleProvider

Abstract base class for module providers (the runtime instances returned by initialize()). It manages a Subscription container for automatic teardown and exposes a SemanticVersion for compatibility checks.

Documentation

Installation

pnpm add @equinor/fusion-framework-module

Quick Start — Defining a Module

import {
  type Module,
  BaseConfigBuilder,
  type ConfigBuilderCallback,
} from '@equinor/fusion-framework-module';
import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';

// 1. Define the configuration shape
interface GreeterConfig {
  greeting: string;
}

// 2. Create a config builder
class GreeterConfigurator extends BaseConfigBuilder<GreeterConfig> {
  setGreeting(cb: ConfigBuilderCallback<string>) {
    this._set('greeting', cb);
  }
}

// 3. Create a provider
class GreeterProvider extends BaseModuleProvider<GreeterConfig> {
  #config: GreeterConfig;

  greet(name: string): string {
    return `${this.#config.greeting}, ${name}!`;
  }

  constructor(args: { version: string; config: GreeterConfig }) {
    super(args);
    this.#config = args.config;
  }
}

// 4. Define the module
export const greeterModule: Module<'greeter', GreeterProvider, GreeterConfigurator> = {
  name: 'greeter',
  configure: () => new GreeterConfigurator(),
  initialize: async ({ config }) => {
    const resolved = await config.createConfigAsync({
      config: {},
      hasModule: () => false,
      requireInstance: () => Promise.reject('no modules'),
    });
    return new GreeterProvider({ version: '1.0.0', config: resolved });
  },
};

Exports

Main Entry Point (@equinor/fusion-framework-module)

Configurator Sub-path (@equinor/fusion-framework-module/configurator)

Plugins Sub-path (@equinor/fusion-framework-module/plugins)

Provider Sub-path (@equinor/fusion-framework-module/provider)

Module Lifecycle

┌─────────────────────────────────────────────────────┐
│                  ModulesConfigurator                 │
├──────────┬──────────────────────────┬────────────────┤
│ Phase    │ Module Hook              │ Consumer Hook  │
├──────────┼──────────────────────────┼────────────────┤
│ Configure│ module.configure()       │ addConfig()    │
│          │ module.postConfigure()   │ onConfigured() │
├──────────┼──────────────────────────┼────────────────┤
│ Init     │ module.initialize()      │                │
│          │ module.postInitialize()  │ onInitialized()│
├──────────┼──────────────────────────┼────────────────┤
│ Plugin   │                          │ registerPlugin │
├──────────┼──────────────────────────┼────────────────┤
│ Dispose  │ module.dispose()         │ instance.      │
│          │                          │  dispose()     │
└──────────┴──────────────────────────┴────────────────┘

Cross-module dependencies with requireInstance

Modules initialize concurrently. Use requireInstance(name, timeout?) inside initialize to wait for a dependency:

initialize: async ({ config, requireInstance, hasModule }) => {
  // Wait for the event module (with optional timeout in ms)
  const event = await requireInstance('event', 5000);
  return new MyProvider(config, event);
},

requireInstance returns a promise that resolves when the requested module finishes initializing. If the module is not registered, the promise rejects.

postInitialize and the full modules map

postInitialize runs after all modules are initialized. It receives the full modules map, making it the right place for cross-module wiring that depends on every module being ready:

postInitialize: async ({ instance, modules }) => {
  // All modules are available here
  modules.event.addEventListener('onContextChanged', (e) => {
    instance.handleContextChange(e.detail);
  });
},

configure and initialize are the two required hooks. postConfigure, postInitialize, and dispose are optional.

Plugins and host-level side effects

Use registerPlugin for application-owned wiring that needs the complete module instance before render. Plugins run after postInitialize and onInitialized, but before initialize() resolves. Return a teardown callback to clean up subscriptions, global listeners, timers, or telemetry bindings during dispose.

import { createPlugin } from '@equinor/fusion-framework-module/plugins';

const contextTelemetryPlugin = createPlugin<[typeof eventModule, typeof telemetryModule]>(
  'contextTelemetry',
  (modules) => modules.event.addEventListener('context:changed', (event) => {
    modules.telemetry.track('context.changed', event.detail);
  }),
);

configurator.registerPlugin(contextTelemetryPlugin);

See Plugins for teardown rules, failure behavior, and API reference.

Events are emitted on configurator.event$ throughout the lifecycle for telemetry and debugging.

Related Packages

• @equinor/fusion-framework-react – React bindings and hooks for consuming modules
• @equinor/fusion-framework-module-http – HTTP client module built on this system
• @equinor/fusion-framework-module-service-discovery – Service discovery module