Skip to main content

Shared Experiments

A lightweight feature-flagging SDK for the Substrate project, built on top of the OpenFeature standard.

Overview​

The shared-experiments package wraps the OpenFeature Server SDK and exposes a simple, opinionated API for evaluating feature flags in server-side applications such as apps/web.

By using OpenFeature, the package is provider-agnostic — you can swap between flagd, LaunchDarkly, Split, Flagsmith, or any other OpenFeature-compatible provider without changing application code.

Installation​

The package is available as a workspace dependency:

# In your app's package.json
"shared-experiments": "workspace:*"

Quick Start​

import {
  setProvider,
  setContext,
  getBooleanFlag,
  getStringFlag,
  shutdown,
} from "shared-experiments";

// 1. Register a provider (once at startup)
await setProvider(myProvider);

// 2. (Optional) Set global evaluation context
setContext({ targetingKey: "user-123", plan: "pro" });

// 3. Evaluate flags anywhere in your code
const darkMode = await getBooleanFlag("dark-mode", false);
const variant = await getStringFlag("checkout-flow", "control");

// 4. Shutdown on app exit
await shutdown();

API Reference​

See the API Reference for full TypeDoc-generated documentation.

Providers​

Environment Variable Provider​

The built-in EnvProvider resolves flags from environment variables using the FEATURE_FLAG_ prefix convention. Ideal for local development and simple deployments.

import { setProvider, getBooleanFlag, EnvProvider } from "shared-experiments";

// FEATURE_FLAG_DARK_MODE=true
await setProvider(new EnvProvider());
const darkMode = await getBooleanFlag("dark-mode", false); // true

Unleash Provider​

The UnleashProvider connects to an Unleash server for production-grade feature management.

Environment Variables​

VariableRequiredDefaultDescription
UNLEASH_API_URLyes—Unleash server API URL
UNLEASH_API_KEYyes—Server-side API token
UNLEASH_APP_NAMEno"substrate"App name sent to Unleash metrics

Quick Start​

import { setProvider, getBooleanFlag, createUnleashProvider } from "shared-experiments";

// Reads UNLEASH_API_URL, UNLEASH_API_KEY, UNLEASH_APP_NAME from env
const provider = createUnleashProvider();
await setProvider(provider);

const darkMode = await getBooleanFlag("dark-mode", false);

Manual Configuration​

import { setProvider, UnleashProvider } from "shared-experiments";

const provider = new UnleashProvider({
  url: "https://unleash.example.com/api",
  apiKey: "my-api-token",
  appName: "my-app",
});
await setProvider(provider);