@buildrflags/sdk

Official Node.js/TypeScript SDK for BuildrFlags — a fast, reliable feature flag platform.

Installation

npm install @buildrflags/sdk
# or
pnpm add @buildrflags/sdk
# or
yarn add @buildrflags/sdk

Quick Start

import { createClient } from '@buildrflags/sdk';

const client = createClient({
  apiKey: 'bf_production_xxxxxxxx',
});

const enabled = await client.isEnabled('new-checkout-flow');

if (enabled) {
  // Show new checkout experience
} else {
  // Show original checkout
}

Configuration

const client = createClient({
  apiKey: 'bf_production_xxxxxxxx',
  baseUrl: 'https://api.flags.buildrlab.com', // Optional
  cacheMs: 60000, // Optional (default: 60000)
  timeoutMs: 5000, // Optional (default: 5000)
  defaultValue: false, // Optional (default: false)
});

Config Options

• apiKey (required): Your BuildrFlags server API key.
• baseUrl (optional): Override API endpoint for self-hosted deployments.
• cacheMs (optional): Cache TTL in milliseconds. Set to 0 to disable cache.
• timeoutMs (optional): Request timeout in milliseconds.
• defaultValue (optional): Value returned when evaluation fails.

API Reference

createClient(config)

Creates a new client instance.

const client = createClient({ apiKey: 'bf_production_xxxxxxxx' });

client.evaluate(flagKey, context?)

Returns a full evaluation result with metadata.

const result = await client.evaluate('my-feature');

console.log(result);
// {
//   flagKey: 'my-feature',
//   enabled: true,
//   reason: 'FLAG_FOUND',
//   fetchedAt: '2024-01-15T10:30:00.000Z',
//   fromCache: false,
// }

client.isEnabled(flagKey, context?)

Convenience method that returns a boolean.

const enabled = await client.isEnabled('my-feature');

client.evaluateAll(flagKeys, context?)

Evaluate multiple flags in parallel.

const results = await client.evaluateAll(['feature-a', 'feature-b']);

for (const [flagKey, result] of results) {
  console.log(flagKey, result.enabled);
}

client.clearCache()

Clears the in-memory cache.

client.clearCache();

client.pruneCache()

Removes expired cache entries without clearing everything.

client.pruneCache();

Evaluation Context

Pass user or request attributes to enable targeting and rollouts.

const enabled = await client.isEnabled('beta-dashboard', {
  userId: 'user-123',
  attributes: {
    plan: 'pro',
    country: 'US',
  },
});

Error Handling

The SDK never throws for evaluation failures. Instead it returns defaultValue and sets the reason to ERROR.

const result = await client.evaluate('maybe-exists');

if (result.reason === 'ERROR') {
  // Log or alert, but your app continues safely.
}

Caching

The SDK includes an in-memory cache to reduce latency and API calls.

• Default TTL: 60 seconds
• Cache key includes flagKey and evaluation context
• Disable with cacheMs: 0

const client = createClient({
  apiKey: 'bf_production_xxxxxxxx',
  cacheMs: 5000,
});

Timeouts

Use timeoutMs to prevent long-running requests.

const client = createClient({
  apiKey: 'bf_production_xxxxxxxx',
  timeoutMs: 2000,
});

TypeScript Support

The package ships with full type definitions.

import {
  createClient,
  type BuildrFlagsConfig,
  type EvaluationContext,
  type EvaluationResult,
} from '@buildrflags/sdk';

Requirements

• Node.js 18 or later
• ES2022 compatible runtime

License

MIT