Firebase Feature Flags

A lightweight, singleton-enforced Firebase Remote Config based library.

This library provides:

• Firebase Remote Config integration.
• URL overrides for debugging: ?ff.myFlag=on.
• Live updates via a subscriber model (React components re-render automatically).
• useFlag() React hook.

Installation

npm install @dartech/firebase-feature-flags-lib

🛠 Setup (Required for Microfrontends)

To ensure all MFEs share the same feature flag state, follow these 3 steps:

1. Update Root Import Map

Add the library to your SystemJS import map. This ensures the browser downloads the code exactly once.

<script type="systemjs-importmap">
{
  "imports": {
     .......,
    "@dartech/firebase-feature-flags-lib": "https://unpkg.com/@dartech/[email protected]/dist/index.js"
  }
}
</script>

2. Configure Bundler Externals

In every microfrontend that uses this library, update bundler.config.js. This tells bundler: "Do not bundle this code; look for it in the browser at runtime."

// bundler.config.js
module.exports = {
  // ...
  externals: [
    "react",
    "react-dom",
    "@dartech/firebase-feature-flags-lib" // <--- ADD THIS
  ],
};

3. Initialize in Topbar MFE

Initialize the flags once in Topbar

import { setDefaults, initFeatureFlags } from "@dartech/firebase-feature-flags-lib";

export const bootstrap = [
  async () => {
    setDefaults({
      'drive.homepage.v2': false,
    });

    await initFeatureFlags({
      apiKey: "...",
      authDomain: "...",
      projectId: "...",
      appId: "...",
    });
  }
];

📖 Usage in Microfrontends

1. React Components (useFlag)

The hook automatically triggers a re-render if flags change (via Remote Config fetch or URL override).

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

export const CheckoutButton = () => {
  const isV2Enabled = useFlag("billing.newCheckout.v2");

  return isV2Enabled ? <NewCheckout /> : <LegacyCheckout />;
};

2. Non-React Logic (getFlag)

Useful for utility functions or sagas.

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

export function calculateFee() {
  if (getFlag("fees.newCalculation")) {
    return logicV2();
  }
  return logicV1();
}

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.a=on&ff.b=off

Priority Order:

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

API Reference

initFeatureFlags(firebaseConfig, opts?)

Initializes Firebase. Should be called once in the Root Config.

• opts.minFetchMs: Cache time in milliseconds (default: 60,000).
• opts.configName: The key in Remote Config to look for (default: "feature_flags").

setDefaults(defaults)

Merges local default values into the singleton store. Safe to call from multiple MFEs.

getFlag(key: string): boolean

Returns current boolean value.

useFlag(key: string): boolean

React Hook that returns the boolean flag and listens for updates.

subscribe(listener: () => void)

Listen for changes. Returns unsubscribe.

Troubleshooting

Problem: My flag is always returning the default value.

1. Check Network: Look for the Remote Config request in the Network tab.
2. Check Singleton: Run this in the console to check details:

   window[Symbol.for("firebase_ff")]

Publishing a New Version

To publish updates to NPM, follow this standard release workflow.

1. Prerequisites

Ensure you are logged into NPM in your terminal and have access to the organization.

npm login

2. Build the Project

Always rebuild the project to ensure the dist/ folder contains the latest TypeScript compilations.

npm run build
npm test

3. Version Bump

Use the npm version command to automatically update package.json, and commit the change.

Choose the appropriate semantic version:

• Patch (Bug fixes): 1.0.0 -> 1.0.1

  npm version patch

• Minor (New features, backward compatible): 1.0.0 -> 1.1.0

  npm version minor

• Major (Breaking changes): 1.0.0 -> 2.0.0

  npm version major

4. Publish

Push the new version to the NPM registry.

npm publish 

5. Push to Git

Push the new version commit and the tags to your repository.

git push