@lovart-open/flags

Type-safe Feature Flag and Parameter Store library built on Statsig, with a fully synchronous architecture.

Installation

npm install @lovart-open/flags
# or
pnpm add @lovart-open/flags

Initialize Statsig

Initialize the Statsig client at your app entry point:

import { initStatsigClient } from '@lovart-open/flags/statsig';

initStatsigClient('your-statsig-client-key', { userID: 'user-123' }, {
  environment: { tier: 'production' },
});

Feature Flags

Core Features

• Type-safe: Full TypeScript type inference and autocomplete
• Synchronous: No loading states, no skeleton screens
• Multi-layer priority: URL > testOverride > override > remote > fallback(false)

Define and Create

import { createFlagStore, type FlagDefinition } from '@lovart-open/flags/statsig';

// 1. Define your flags
const MY_FLAGS = {
  dark_mode: { 
    description: 'Dark mode toggle' 
  },
  new_checkout: { 
    description: 'New checkout flow',
    testOverride: true,  // Force enable in E2E tests
  },
  beta_feature: {
    description: 'Beta feature',
    override: false,     // Static override, ignores remote
  },
} as const satisfies Record<string, FlagDefinition>;

// 2. Create type-safe store and hooks
export const { 
  flagStore, 
  useFlag, 
  useFlagState 
} = createFlagStore(MY_FLAGS);

// 3. Export types (optional)
export type MyFlagKey = keyof typeof MY_FLAGS;

React Usage

import { useFlag, useFlagState } from './my-flags';

function App() {
  // Get boolean value directly
  const isDark = useFlag('dark_mode');  // ✓ autocomplete
  
  // Get full state with source info
  const state = useFlagState('new_checkout');
  console.log(state.flag, state.source);  // true, 'remote'
  
  return isDark ? <DarkTheme /> : <LightTheme />;
}

Non-React Usage

import { flagStore } from './my-flags';

// Get single flag
const enabled = flagStore.getFlag('dark_mode');

// Get snapshot of all flags
const snapshot = flagStore.snapshot;

URL Override for Debugging

?ff.dark_mode=1    → Force enable
?ff.dark_mode=0    → Force disable

Parameter Store

Core Features

• Type-safe: Zod schema validation + TypeScript inference
• Synchronous: Same as Feature Flags
• Multi-layer priority: URL > testOverride > override > remote > fallback

Define and Create

import { z } from 'zod';
import { 
  createParamStore, 
  defineParam, 
  type ParamStoreDefinition 
} from '@lovart-open/flags/statsig';

// 1. Define your param stores
const MY_PARAMS = {
  homepage_cta: {
    description: 'Homepage CTA button',
    params: {
      text: defineParam({
        schema: z.enum(['Learn More', 'Get Started', 'Sign Up']),
        fallback: 'Learn More',
        description: 'Button text',
      }),
      color: defineParam({
        schema: z.enum(['gray', 'red', 'blue']),
        fallback: 'gray',
        testOverride: 'blue',  // Use in E2E tests
      }),
      visible: defineParam({
        schema: z.boolean(),
        fallback: true,
      }),
    },
  },
  pricing: {
    description: 'Pricing config',
    params: {
      discount: defineParam({
        schema: z.number().min(0).max(100),
        fallback: 0,
      }),
      currency: defineParam({
        schema: z.enum(['USD', 'CNY', 'EUR']),
        fallback: 'USD',
      }),
    },
  },
} as const satisfies Record<string, ParamStoreDefinition<any>>;

// 2. Create type-safe store and hooks
export const { 
  paramStore, 
  useParam, 
  useParamState, 
  useParamStore 
} = createParamStore(MY_PARAMS);

React Usage

import { useParam, useParamStore } from './my-params';

function CTAButton() {
  // Get value directly (with full type hints)
  const text = useParam('homepage_cta', 'text');   // 'Learn More' | 'Get Started' | 'Sign Up'
  const color = useParam('homepage_cta', 'color'); // 'gray' | 'red' | 'blue'

  // Or get entire store handle
  const store = useParamStore('homepage_cta');
  const visible = store.get('visible');  // boolean

  if (!visible) return null;
  return <button style={{ color }}>{text}</button>;
}

Non-React Usage

import { paramStore } from './my-params';

// Get single param
const discount = paramStore.getParam('pricing', 'discount');  // number

// Get store handle
const store = paramStore.getStore('pricing');
store.get('currency');  // 'USD' | 'CNY' | 'EUR'

URL Override for Debugging

# Single param override
?fp.homepage_cta.text=Get Started
?fp.pricing.discount=20

# Entire store JSON override
?fp.homepage_cta={"text":"Get Started","visible":false}

Advanced Configuration

Custom Logger

import { initStatsigClient, setLogger } from '@lovart-open/flags/statsig';

// Option 1: Pass during init
initStatsigClient('client-xxx', { userID: 'user-123' }, {
  logger: (message) => myLogger.info(message),
});

// Option 2: Set globally
setLogger((message) => myLogger.info(message));

E2E Test Support

Configure isTestEnv in initialization to enable testOverride values:

initStatsigClient('client-xxx', { userID: 'user-123' }, {
  isTestEnv: () => Boolean(window.__E2E__),
});

// playwright/cypress tests
await page.addInitScript(() => {
  window.__E2E__ = true;
});

Server-Side Bootstrap (Zero-Network Init)

initStatsigClient('client-xxx', { userID: 'user-123' }, {
  bootstrap: {
    data: bootstrapDataFromServer,  // Pre-fetched from BFF
  },
});

FlagDefinition Options

| Property | Type | Description | |----------|------|-------------| | description | string | Human-readable description | | testOverride | boolean | Fixed value in E2E tests | | override | boolean | Static override (priority over remote) | | keep | boolean | Mark as kept locally (no remote needed) |

ParamDefinition Options

| Property | Type | Description | |----------|------|-------------| | schema | z.ZodType | Zod schema (required) | | fallback | T | Default value (required) | | description | string | Human-readable description | | testOverride | T | Fixed value in E2E tests | | override | T | Static override |

License

MIT