@nexussdk/flags

@nexussdk/flags

Ultra-lightweight, production-grade feature flags and remote config client SDK for browsers and edge runtimes with MurmurHash3 bucketing, ABAC rule evaluation, real-time SSE hot-swapping, and zero-infra local dev server (< 6KB gzipped).

Key Features

Core (all versions):

• Deterministic Rollout: Pure TypeScript MurmurHash3 32-bit guarantees deterministic 0–100% bucketing matching server-side evaluation.
• ABAC Rule Engine: Full attribute-based access control — string, number, array operators (IN, CONTAINS, STARTS_WITH), comparison, and semantic versioning rules.
• Real-Time Streaming (SSE): SSEManager with singleton connection pooling, exponential backoff reconnects, and instant FLAG_UPDATE / FLAG_DELETE live sync.
• Offline-First & Bootstrap: Instant 0ms boot via bootstrap options (SSR pre-evaluation, local JSON, or boolean dictionary) with background revalidation.
• Cross-Tab Synchronization: In-memory cache backed by localStorage and BroadcastChannel.
• Built-in Local Dev Server: nexus-flags-dev CLI with single-file web dashboard and live SSE broadcasting.

Advanced Capabilities & Resilience (v0.0.8+ / v0.0.9):

• 🧹 Stale Flag Detector: StaleFlagDetector scans your active flags and emits [NEXUS_STALE_FLAG] warnings for any flag that has been at 100% rollout longer than your configured threshold (default: 30 days). Eliminates the "flag graveyard" problem.
• ⚡ Resilient SSE Reconnection: Backoff-reconnecting Server-Sent Events stream manager with exponential jitter and fallback snapshot polling.
• 🔄 Cross-Tab Synchronization: Real-time flag state synchronization across browser tabs using BroadcastChannel with fallback to localStorage events.

Installation

pnpm add @nexussdk/flags
# or
npm install @nexussdk/flags

(If using React or Vue, install @nexussdk/sdk instead for built-in hooks like useFeatureFlag and useVariant).

Quickstart (Vanilla JS / TypeScript)

import { NexusFlagsClient } from '@nexussdk/flags';

// 1. Initialize client
const flags = new NexusFlagsClient({
  apiKey: 'pk_live_your_api_key',
  baseUrl: 'https://api.nexus.dev',
  user: {
    id: 'usr_4829',
    country: 'VN',
    plan: 'enterprise',
    appVersion: '2.4.0',
  },
  realtime: true, // Enable SSE live streaming
});

// 2. Synchronous evaluation (0ms from cache / bootstrap)
if (flags.isEnabled('new_checkout_flow', false)) {
  mountNewCheckout();
} else {
  mountLegacyCheckout();
}

// 3. Dynamic variant configurations
const discountRate = flags.getVariant<number>('promo_banner_v2', 'discount_rate', 0);
const layoutTheme = flags.getVariant<string>('checkout_v2', 'theme', 'standard');

// 4. Listen for realtime hot-swap updates
const unsubscribe = flags.onFlagChange('new_checkout_flow', (result) => {
  console.log('Flag updated in realtime:', result.enabled, result.reason);
  if (result.enabled) {
    mountNewCheckout();
  }
});

// 5. Update user identity (e.g. after login)
await flags.identify({
  id: 'usr_9981',
  country: 'SG',
  plan: 'pro',
});

// 6. Reset user on logout
flags.reset();

// 7. Cleanup on unmount
unsubscribe();
flags.destroy();

Configuration Options (NexusFlagsOptions)

Offline & Bootstrap Mode (Local JSON)

For small projects or offline development, you can completely bypass backend servers by bootstrapping flags from a local JSON file:

import localFlags from './nexus-flags.json';

const flags = new NexusFlagsClient({
  bootstrap: localFlags,
  realtime: false, // Optional: disable network calls completely
});

// Ready immediately without any network calls
const isDarkMode = flags.isEnabled('dark_mode', false);

The bootstrap parameter accepts:

• Simple boolean flags: { dark_mode: true, beta_ui: false }
• Standard nexus-flags.json objects created by the dev server
• Full FlagEvaluationResult maps generated from SSR

Local Dev Server (nexus-flags-dev)

The @nexussdk/flags package includes a standalone local flag management CLI with an embedded Web GUI dashboard:

# Start local flag management server
npx nexus-flags-dev
# or in this monorepo
pnpm --filter @nexussdk/flags flags-server

CLI Options

nexus-flags-dev [options]

Options:
  -p, --port <number>   Port to listen on (default: 4568)
  --host <string>       Host interface to bind (default: localhost)
  -f, --file <path>     Path to JSON flags file (default: ./nexus-flags.json)
  -h, --help            Show help message

Endpoints

Connecting SDK to Local Dev Server

const client = new NexusFlagsClient({
  apiKey: 'nxs_dev_local',
  baseUrl: 'http://localhost:4568',
  realtime: true, // Whenever you toggle a flag in the GUI, your app updates instantly!
});

Programmatic Dev Server Export

You can also embed the flags dev server programmatically in your test harness or Vite dev server:

import { startFlagsDevServer } from '@nexussdk/flags/dev-server';

const devServer = await startFlagsDevServer({
  port: 4568,
  flagsFile: './test-flags.json',
  seed: true,
});

// Later in teardown:
await devServer.close();

Framework Compatibility Matrix

@nexussdk/flags is completely framework-agnostic with zero runtime dependencies. It supports modern and legacy frontends:

License

MIT © Nexus Platform