Skip to main content

Shared Experiments

Feature flagging SDK wrapping OpenFeature for the Substrate project.

For detailed usage documentation, see the Shared Experiments documentation on the docs site.

Contributing​

Prerequisites​

  • Node.js 20+ and Yarn
  • Understanding of OpenFeature concepts
  • Familiarity with feature flags and experimentation

Commands​

# Build the package
nx build shared-experiments

# Run tests
nx test shared-experiments

# Lint the package
nx lint shared-experiments

Project Structure​

packages/shared-experiments/
├── src/
│   ├── lib/
│   │   ├── experiments.ts        # Core feature-flag helpers
│   │   ├── env-provider.ts       # Environment variable provider
│   │   └── unleash-provider.ts   # Unleash provider
│   └── index.ts                  # Package exports
├── docs/                         # Documentation (built to docs site)
└── README.md                     # This file

Key Exports​

The package provides simple wrappers around the OpenFeature server SDK:

  • setProvider(provider, clientName?) – Register a feature-flag provider
  • setContext(context) – Set shared evaluation context
  • getClient(name?) – Get an OpenFeature client
  • getBooleanFlag(key, default, context?, clientName?) – Evaluate a boolean flag
  • getStringFlag(key, default, context?, clientName?) – Evaluate a string flag
  • getNumberFlag(key, default, context?, clientName?) – Evaluate a numeric flag
  • getObjectFlag(key, default, context?, clientName?) – Evaluate an object flag
  • getBooleanFlagDetails(key, default, context?, clientName?) – Boolean flag with details
  • getStringFlagDetails(key, default, context?, clientName?) – String flag with details
  • getNumberFlagDetails(key, default, context?, clientName?) – Number flag with details
  • shutdown() – Close OpenFeature and release resources

Providers​

  • EnvProvider – Resolve flags from FEATURE_FLAG_* environment variables
  • UnleashProvider – Connect to an Unleash server
  • createUnleashProvider() – Factory that reads Unleash config from env vars (UNLEASH_API_URL, UNLEASH_API_KEY, UNLEASH_APP_NAME)

Usage Example​

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

// 1. Set a provider (e.g. flagd, LaunchDarkly, etc.)
await setProvider(myProvider);

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

// 3. Evaluate flags
const darkMode = await getBooleanFlag("dark-mode", false);