Flags SDK - Flagsmith Provider

The Flagsmith provider for the Flags SDK contains support for Flagsmith's Feature Flags and Remote Configuration.

Setup

The Flagsmith provider is available in the @flags-sdk/flagsmith module. You can install it with

npm i @flags-sdk/flagsmith

Set the required environment variable:

export FLAGSMITH_ENVIRONMENT_KEY="your-server-side-environment-key"

Usage

The Flagsmith adapter provides a getValue() method with optional type coercion:

import { flag } from "flags/next";
import { flagsmithAdapter } from "@flags-sdk/flagsmith";

// No coercion - returns the raw value from Flagsmith
export const rawFlag = flag({
  key: "raw-value",
  defaultValue: "default",
  adapter: flagsmithAdapter.getValue(),
});

// Coerce to string type
export const buttonColor = flag<string>({
  key: "button-color",
  defaultValue: "blue",
  adapter: flagsmithAdapter.getValue({ coerce: "string" }),
});

// Coerce to number type
export const maxItems = flag<number>({
  key: "max-items",
  defaultValue: 10,
  adapter: flagsmithAdapter.getValue({ coerce: "number" }),
});

// Coerce to boolean type
export const showBanner = flag<boolean>({
  key: "show-banner",
  defaultValue: false,
  adapter: flagsmithAdapter.getValue({ coerce: "boolean" }),
});

Type Coercion Behavior

• Without coerce: Returns the raw value from Flagsmith (empty/null/undefined values return default)
• coerce: "string": Converts any value to string (returns default for null/undefined/NaN)
• coerce: "number": Converts strings to numbers (returns default if result is NaN or invalid)
• coerce: "boolean":
  • Converts "true"/"false" strings (case-insensitive) to boolean
  • Converts 0 to false and 1 to true
  • Falls back to the flag's enabled state for other values
  • Returns default when flag is disabled

Custom Adapter

Create a custom adapter by using the createFlagsmithAdapter function:

import { createFlagsmithAdapter, EntitiesType } from "@flags-sdk/flagsmith";

const identify: Identify<EntitiesType> = dedupe(async () => {
  return {
    targetingKey: "user",
    traits: {
      id: "e23cc9a8-0287-40aa-8500-6802df91e56a",
      name: "John Doe",
      email: "[email protected]",
    },
  };
});

const adapter = createFlagsmithAdapter({
  environmentKey: "your-server-side-environment-key",
  // Additional @flagsmith/nodejs configuration options
});

export const showBanner = flag<boolean, EntitiesType>({
  key: "show-banner",
  identify,
  adapter: adapter.getValue({ coerce: "boolean" }),
});

Flags Discovery Endpoint

To enable the Flags Explorer, create a discovery endpoint at app/.well-known/vercel/flags/route.ts:

import { createFlagsDiscoveryEndpoint } from "flags/next";
import { getProviderData } from "@flags-sdk/flagsmith";

export const GET = createFlagsDiscoveryEndpoint(async () => {
  return getProviderData({
    environmentKey: process.env.FLAGSMITH_ENVIRONMENT_KEY,
    projectId: process.env.FLAGSMITH_PROJECT_ID,
  });
});

This endpoint fetches flag definitions directly from Flagsmith's API and returns them to the Flags Explorer.

Environment Variables

• FLAGSMITH_ENVIRONMENT_KEY (required): Your Flagsmith server-side environment key
• FLAGSMITH_PROJECT_ID (optional): Required for the Flags Discovery Endpoint

Documentation

Please check out the Flagsmith provider documentation for more information.

License

MIT

Server-side evaluation

The adapter uses @flagsmith/nodejs and requires a Node.js runtime. Remote evaluation is the default, suitable for serverless deployments: it fetches evaluated flags from Flagsmith without downloading an environment document or starting background polling. Set FLAGSMITH_ENVIRONMENT_KEY to your Flagsmith environment key and keep it on the server.

One client is shared per adapter. Use evaluate([flagA, flagB]) from flags/next to batch flags: the Flags SDK groups flags by adapter and identify function, and the adapter fetches all values once per batch. Different coercion modes form separate batches to preserve their value types. Individual flag calls use decide() and do not share an adapter-level result cache. User identities are passed to getIdentityFlags rather than stored as the client's current user. Remote identity evaluation persists supplied traits in Flagsmith.

For a long-running server, opt into local evaluation with one option:

const adapter = createFlagsmithAdapter({
  environmentKey: process.env.FLAGSMITH_ENVIRONMENT_KEY,
  enableLocalEvaluation: true,
});

Local evaluation requires a server-side environment key (starting with ser.). It downloads the environment document and polls for updates every 60 seconds. Each new client must initialize this document, so prefer remote evaluation for short-lived serverless instances. Set environmentRefreshIntervalSeconds to change the refresh interval and call await adapter.close() on shutdown to stop polling. The default flagsmithAdapter also exposes close().

Local evaluation does not persist supplied traits to the Flagsmith API. However, @flagsmith/nodejs 9.0.3 may retain previously supplied traits for identities with overrides, even when later evaluations of the same identity omit those traits. For example, evaluating an identity with { tier: "gold" } and then with {} may still use tier: "gold" on the second evaluation.

Migration from the JavaScript SDK adapter

• Replace client-side environment keys with server-side keys for local evaluation.
• Use environmentKey instead of environmentID in custom configuration. environmentID is no longer supported.
• Use server SDK options such as apiUrl instead of api. Browser SDK options such as cacheFlags, state, and onChange are no longer supported.
• Pass user identity and traits through the flag's identify function.
• Remote evaluation remains the default. Set enableLocalEvaluation: true to opt into local evaluation on a long-running server.