DMS Feature Flags

A lightweight Firebase Remote Config powered feature flag library.

This library provides:

• Firebase Remote Config integration
• URL overrides for debugging: ?ff.myFlag=on / off
• Live updates via a subscriber model
• useFlag() React hook

Installation

npm install @dartech/dms-feature-flags
# or
yarn add @dartech/dms-feature-flags
# or
pnpm add @dartech/dms-feature-flags

Quick Start

1. Set Defaults (before initializing)

It is crucial to set all expected flags and their default values before calling initFeatureFlags. Only flags defined here are considered by the library.

import { setDefaults } from "@dartech/dms-feature-flags";

setDefaults({
  "billing.newCheckout.v2": false,
  "ui.darkMode.toggle": false,
  "feed.layout.v3": true,
});

2. Initialize Firebase + Remote Config

Call this once, ideally in your app root or MFE entrypoint.

import { initFeatureFlags } from "@dartech/dms-feature-flags";

await initFeatureFlags(
  {
    apiKey: "...",
    authDomain: "...",
    projectId: "...",
    appId: "...",
  },
  { 
    minFetchMs: 60_000 // optional: minimum time between fetches (default is 60s)
    configName: "feature_flags" // optional: Firebase RC name (default is "feature_flags")
  } 
);

⚠️ Calling initFeatureFlags() more than once is safe, but subsequent calls will be ignored.

3. Use Feature Flags

In React:

Use the dedicated hook for auto-updating components.

import {useFlag} from "@dartech/dms-feature-flags";

const isEnabled = useFlag("feed.layout.v3");

Anywhere (services, utils, plain JS):

import { getFlag } from "@dartech/dms-feature-flags";

if (getFlag("feed.layout.v3")) {
  // enable feature logic
}

URL Overrides for Debugging

You can override any flag directly in the browser URL using the ff. prefix. This is the highest priority resolution method.

• Enable a flag: ?ff.feed.layout.v3=on
• Disable a flag: ?ff.feed.layout.v3=off
• Multiple flags: ?ff.feed.layout.v3=on&ff.ui.darkMode.toggle=off

Changes update automatically on browser navigation (popstate).

Priority Order

When resolving a flag's value, the library checks in the following order:

1. URL override
2. Remote Config value
3. Default

useFlag() Hook

const value = useFlag("featureName", fallback?);

Features:

• Auto-updates when flags change (via Remote Config fetch or URL navigation).
• Optional fallback if the flag doesn’t exist (though all flags should be defined in setDefaults).

Example:

function Checkout() {
  const showNewCheckout = useFlag("billing.newCheckout.v2");

  return showNewCheckout ? <NewCheckout /> : <DefaultCheckout />;
}

API Reference

setDefaults(defaults)

Set default flag values before calling initFeatureFlags().

initFeatureFlags(firebaseConfig, opts?)

Initializes Firebase and Remote Config.

opts = {
  minFetchMs?: number; // default 60 seconds
  configName?: string; // default "feature-flags"
}

getFlag(key: string): boolean

Returns a boolean flag.

Priority: URL override > Remote Config > Defaults.

subscribe(listener: () => void): () => void

Subscribe to internal flag changes (e.g., after a Remote Config update or URL navigation). Returns an unsubscribe() function.

getUrlOverride(key: string): boolean | null

Returns:

• true / false if the flag is currently overridden via the URL.
• null if the flag is not overridden.

Remote Config Format

Remote Config must contain a JSON string under the key: feature_flags (or any custom key you configure)

Example Remote Config data (JSON string value):

{
  "billing.newCheckout.v2": true,
  "ui.darkMode.toggle": false,
  "feed.layout.v3": true
}

Important: Only flags explicitly defined in setDefaults() are considered by the library.

Debugging Tips

• Check if a flag is overridden by the URL:

  console.log(getUrlOverride("myFlag"));