@equinor/fusion-framework-module-feature-flag

Fusion Framework module for managing feature flags in applications. Provides a plugin-based architecture for defining, persisting, and toggling feature flags from multiple sources such as local storage, URL query parameters, or a remote API.

Features

• Plugin architecture — compose multiple flag sources (local storage, URL, API) into one provider.
• Local-storage persistence — toggled flags survive page reloads via createLocalStoragePlugin.
• URL toggle — enable or disable flags through query parameters with createUrlPlugin.
• Remote API — fetch flags from an HTTP endpoint using createApiPlugin.
• Observable state — subscribe to flag changes via RxJS observables.
• Framework events — emits onFeatureFlagToggle (cancelable) and onFeatureFlagsToggled when the event module is present.
• Typed values — flags can carry a generic typed payload (IFeatureFlag<T>).

Installation

pnpm add @equinor/fusion-framework-module-feature-flag

Usage

Register the module

import { enableFeatureFlagging } from '@equinor/fusion-framework-module-feature-flag';
import {
  createLocalStoragePlugin,
  createUrlPlugin,
} from '@equinor/fusion-framework-module-feature-flag/plugins';

export const configure = (configurator) => {
  enableFeatureFlagging(configurator, (builder) => {
    // Persist toggled state in localStorage
    builder.addPlugin(
      createLocalStoragePlugin([
        { key: 'dark-mode', title: 'Dark mode' },
        { key: 'beta-search', title: 'Beta search', enabled: false },
      ]),
    );
    // Allow toggling via URL: ?beta-search=true
    builder.addPlugin(createUrlPlugin(['beta-search']));
  });
};

Read flags at runtime

const featureFlags = modules.featureFlag;

// Check a single flag
if (featureFlags.getFeature('dark-mode')?.enabled) {
  applyDarkTheme();
}

// Observe changes
featureFlags.features$.subscribe((features) => {
  console.log('Current flags:', features);
});

Toggle flags programmatically

await featureFlags.toggleFeature({ key: 'dark-mode', enabled: true });

Fetch flags from an API

import { createApiPlugin } from '@equinor/fusion-framework-module-feature-flag/plugins';

builder.addPlugin(
  createApiPlugin({
    httpClientName: 'my-api',
    path: '/feature-flags',
  }),
);

API Reference

Main exports (@equinor/fusion-framework-module-feature-flag)

Plugin exports (@equinor/fusion-framework-module-feature-flag/plugins)

Selector exports (@equinor/fusion-framework-module-feature-flag/selectors)

Mock exports (@equinor/fusion-framework-module-feature-flag/mock)

Operational telemetry

IFeatureFlagProvider extends TelemetryConnectable. The provider uses telemetry.scope('feature-flag'), with a lazy factory fallback for older custom providers; closing the handle cancels pending toggles once and prevents late reporting. Toggle summaries remain specific to this module.

When the host registers telemetry, each toggleFeature/toggleFeatures call reports one fusion.feature-flag.toggle.duration outcome with requested, applied, rejected (unregistered or read-only) and cancelled (listener veto or superseded listener work) counts. Bulk toggles retain their existing latest-only application behavior; superseded listeners count as cancelled before the call's outcome is exported. A call whose applicable flags were all vetoed is cancelled; a toggle still awaiting listeners when the module is disposed is cancelled with reason disposed. The module now disposes its provider at host teardown, which also releases plugin connections. Reads such as hasFeature are never recorded, and feature keys and values are never exported. See Operational telemetry.

Testing

Import from @equinor/fusion-framework-module-feature-flag/mock to seed flags in-memory instead of depending on localStorage or the URL. The real FeatureFlagProvider, toggling, and subscriptions still run — only the flag source is substituted.

import { enableFeatureFlagMock } from '@equinor/fusion-framework-module-feature-flag/mock';

enableFeatureFlagMock(configurator, (mock) => {
  mock.addFeature({ key: 'my-flag', enabled: true });
});

Defaults

No flags are assumed by default. A test that seeds nothing gets an empty features object, matching the real module's zero-plugin behavior. setFeatures seeds several flags and addFeature adds or replaces one flag by key. Toggling still runs through the real FeatureFlagProvider; the mock substitutes only the initial flag source.

Configuration

The module is configured through enableFeatureFlagging(configurator, callback). Inside the callback you receive an IFeatureFlagConfigurator builder with the following methods:

Plugin lifecycle

1. During configuration each plugin factory is registered via addPlugin.
2. At module initialisation every factory is called with ConfigBuilderCallbackArgs.
3. Each plugin returns its initial() flags and an optional connect() hook.
4. The provider merges all initial flags and invokes connect() so plugins can subscribe to toggle events (e.g. to persist changes).
5. the configurator return an instance of the config
6. the module create a provider instance
7. the provider connects the plugins
8. the provider subscribes to toggle actions and connects plugin toggle handlers
9. the module returns the feature flag module to the framework

export interface FeatureFlagPlugin {
    /**
     * connect the plugin to the provider
     */
    connect: (args: { provider: IFeatureFlagProvider }) => VoidFunction | Subscription;

    /**
     * generate initial value for the provider
     */
    initial?: () => ObservableInput<Array<IFeatureFlag>>;
}

Local Storage

import { createLocalStoragePlugin } from '@equinor/fusion-framework-module-feature-flag/plugins';

plugin for allowing to store the toggled state of a feature flag

Url

import { createUrlPlugin } from '@equinor/fusion-framework-module-feature-flag/plugins';

plugin for toggling features threw url search params

Custom

initial

async callback function which returns the initial feature flags of the plugin

connect

async callback which allows the plugin to connect to the feature flag provider

import { 
  enableFeatureFlagging, 
  type FeatureFlagPluginConfigCallback 
} from '@equinor/fusion-framework-module-feature-flag';

const customPlugin: FeatureFlagPluginConfigCallback = async (args) => {
  const myModule = await args.requireModule('my-module');
  return {
    initial: () => fetch('/api/features')
      .then(res => res.json())
      .then(features => features.map(feature => feature.source = 'my-source')),
    connect: ({provider}) => {
      /** subscribe to changes of feature flags */
      provider.onFeatureToggle: async({flags}) => {
        await fetch(
          '/api/me/features', 
          { 
            method: 'PATCH', 
            body: flags.filter(feature => feature.source === 'my-source')
          }
        )
      }
      /** update feature flags */
      signalR.received(data => {
        provider.setFeatures(data.map(feature => feature.source = 'my-source'));
      });
    },
  }
}

// ...configuration
enableFeatureFlagging(builder => {
  builder.addPlugin(customPlugin);
})

Selectors

Filter features

Operator function for filtering out specific features

import { filterFeatures } from '@equinor/fusion-framework-module-feature-flag/selectors';
const features$ = modules.featureFlag.feature$.pipe(
  filterFeatures(x => x.enabled = true);
);

Find feature

Operator for selecting a specific feature

[!IMPORTANT] The operator will not re-emit unless value or selector changes

import { findFeature } from '@equinor/fusion-framework-module-feature-flag/selectors';
const feature$ = modules.featureFlag.feature$.pipe('my-key');

Events

onFeatureFlagToggle

Event fired before a feature is toggled

onFeatureFlagsToggled

Event fired after features are toggled (state updated)

Usage

// my-code.ts
const provider = modules.featureFlag;
const fooEnabled = provider.getFeatures('foo').enabled;
console.log('feature foo is ', fooEnabled ? 'enabled' : 'disabled');