@ameykhale/contentstack-flagbearer-provider

An OpenFeature-compatible feature flags provider for Contentstack, powered by the Flagbearer Marketplace App.

Prerequisites

This SDK reads feature flags that are managed by the Flagbearer Contentstack Marketplace App. Before using the SDK:

1. Install the Flagbearer app from the Contentstack Marketplace into your organization
2. During installation, complete the configuration screen:
   • Select your stack from the dropdown (all stacks in your org are listed)
   • Enter your stack publishing environment — the Contentstack environment where flag entries will be published (e.g. "prod", "default"). This must already exist in your stack. This is the same environment you'll need to pass in the SDK's config.
   • Add your flag environments — logical names for your application environments (e.g. "development", "staging", "production"). Each gets its own independent set of flags. Configuration saves automatically once all fields are filled.
3. Open the Flagbearer app from the app switcher — it automatically creates the content model and one flags entry per flag environment
4. Use the app's UI to create and toggle flags — changes are saved and published to your stack
5. For ready-to-copy code snippets pre-filled with your config, use the </> button in the app

Once the app is set up, use this SDK to read flags in your Node.js application.

Installation

npm install @ameykhale/contentstack-flagbearer-provider @openfeature/core @contentstack/delivery-sdk

Quick Start

import { createFlagProvider } from "@ameykhale/contentstack-flagbearer-provider";

const provider = await createFlagProvider({
  stackApiKey: "your_stack_api_key",
  deliveryToken: "your_delivery_token",
  stackEnvironment: "production",   // Contentstack publishing environment
  flagEnvironment: "production",    // Logical flag environment name (as set in the app)
});

// Use with OpenFeature
import { OpenFeature } from "@openfeature/core";

OpenFeature.setProvider(provider);
const client = OpenFeature.getClient();

const isEnabled = await client.getBooleanValue("enable_new_dashboard", false);

// Cleanup when done
await provider.onClose();

Configuration

ContentstackFlagbearerConfig

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | stackApiKey | string | Yes | — | Contentstack stack API key | | deliveryToken | string | Yes | — | Contentstack delivery token for the publishing environment | | stackEnvironment | string | Yes | — | Contentstack publishing environment name (e.g. "production") | | flagEnvironment | string | Yes | — | Logical flag environment name as configured in the Flagbearer app (e.g. "production") | | refreshIntervalMs | number | No | 60000 | How often (in ms) to refresh flags from Contentstack |

Two environment concepts

The SDK uses two distinct environment identifiers that usually share the same name but serve different purposes:

• stackEnvironment — the Contentstack publishing environment. This is where the Flagbearer app publishes flag entries to, and where the SDK reads from via the Delivery API. You can find this in your Contentstack stack settings and it is the environment you choose in Flagbearer app's configuration.
• flagEnvironment — the logical flag environment name you defined in the Flagbearer app (e.g. "development", "staging", "production"). This determines which set of flags the SDK fetches.

Error Handling

The SDK provides three custom error classes:

• FlagbearerInitializationError — thrown if the provider fails to initialize (e.g. bad credentials, missing entry)
• FlagbearerApiError — thrown on API communication failures
• FlagResolutionError — thrown during flag evaluation failures

import {
  createFlagProvider,
  FlagbearerInitializationError,
} from "@ameykhale/contentstack-flagbearer-provider";

try {
  const provider = await createFlagProvider(config);
} catch (error) {
  if (error instanceof FlagbearerInitializationError) {
    console.error("Failed to initialize provider:", error.message);
  }
}

Advanced Usage

For more control, use the internal classes directly:

import {
  ContentStackClient,
  FlagStore,
  ContentstackFlagbearerProvider,
} from "@ameykhale/contentstack-flagbearer-provider";

const client = new ContentStackClient(stackApiKey, stackEnvironment, deliveryToken);
const store = new FlagStore(client, flagEnvironment, refreshIntervalMs);
await store.initialize();

const provider = new ContentstackFlagbearerProvider(store);

// Manually refresh flags
await store.refresh();

// Get all flags
const flags = store.getFlags();

// Get a single flag value
const isFlagEnabled = store.getFlagValue("enable_new_dashboard");

Cleanup

Always call onClose() when shutting down to stop the background refresh interval:

await provider.onClose();

License

MIT