@forge/feature-flags-node

A feature flag SDK for Atlassian Forge apps running on Forge Node Runtime. This package provides a simple interface for evaluating feature flags.

Installation

1yarn add @forge/feature-flags-node

Usage

Basic Usage

1import { getAppContext } from "@forge/api";
2import { ForgeFeatureFlags } from "@forge/feature-flags-node";
3
4export const handler = async (payload, context) => {
5  const { environmentType } = getAppContext();
6
7  // Initialize the feature flags service
8  const featureFlags = new ForgeFeatureFlags();
9  await featureFlags.initialize({
10    environment: environmentType?.toLowerCase() || "development" // Optional, defaults to 'development'
11  });
12
13  // Define a user
14  const user = {
15    userID: context?.principal?.accountId,
16    custom: { 
17      license: context?.license?.isActive
18    }
19  };
20
21  // Check a feature flag (synchronous after initialization)
22  const isEnabled = featureFlags.checkFlag(user, "new-feature");
23
24  // Get multiple flags at once (synchronous)
25  const flags = featureFlags.getFeatureFlags(user, ["feature-a", "feature-b"]);
26
27  // Shutdown when done
28  await featureFlags.shutdown();
29}
30

⚠️ Important: Initialization Best Practices

ALWAYS initialize the ForgeFeatureFlags SDK inside your handler function, NEVER initialize globally as it will use the stale feature flags

✅ Correct Pattern - Initialize Inside Handler

1import { getAppContext } from "@forge/api";
2import { ForgeFeatureFlags } from "@forge/feature-flags-node";
3
4export const handler = async (payload, context) => {
5  // ✅ Initialize inside the handler function
6  const featureFlags = new ForgeFeatureFlags();
7  await featureFlags.initialize({
8    environment: getAppContext().environmentType?.toLowerCase() || "development"
9  });
10
11  // Use feature flags...
12  const isEnabled = featureFlags.checkFlag(user, "new-feature");
13
14  // Shutdown when done
15  await featureFlags.shutdown();
16}

❌ Incorrect Pattern - Global Initialization

1// ❌ NEVER do this - Global initialization
2const featureFlags = new ForgeFeatureFlags();
3await featureFlags.initialize(); // This will cause problems!
4
5export const handler = async (payload, context) => {
6  // This will fail if token expires or network issues occur
7  const isEnabled = featureFlags.checkFlag(user, "new-feature");
8}

Polling Behavior

The package automatically polls for feature flag updates every 30 seconds:

1. Cache Updates: New data is cached for fallback purposes
2. Error Resilience: If a fetch fails, the package falls back to cached data
3. Immediate Updates: Feature flag changes are reflected within 30 seconds

1// Polling happens automatically in the background
2const featureFlags = new ForgeFeatureFlags();
3await featureFlags.initialize();
4
5// Feature flags are automatically updated every 30 seconds
6// No manual intervention required

API Reference

ForgeFeatureFlags

constructor()

Creates a new instance of the ForgeFeatureFlags class.

initialize(config?: ForgeFeatureFlagConfig): Promise<void>

Initializes the feature flags service with the provided configuration.

1interface ForgeFeatureFlagConfig {
2  environment?: 'development' | 'staging' | 'production';
3}

checkFlag(user: ForgeUser, flagName: string): boolean

Checks if a feature flag is enabled for the given user. Synchronous after initialization.

getFeatureFlags(user: ForgeUser, flagNames: string[]): Record<string, boolean>

Gets multiple feature flags at once. Synchronous after initialization.

shutdown(): Promise<void>

Shuts down the feature flags service and cleans up resources.

isInitialized(): boolean

Checks if the service is initialized.

User Interface

1interface ForgeUser {
2  userID: string;
3  custom?: Record<string, string | number | boolean>;
4}

Configuration Options

Option	Type	Default	Description
environment	'development' | 'staging' | 'production'	'development'	Environment tier for feature flag evaluation