@flagdrop/sdk

Feature flag management where evaluations run entirely inside your cloud. No vendor servers. No data leaving your infrastructure.

FlagDrop pushes a lightweight JSON config to a storage bucket in your cloud account. The SDK reads that file and evaluates flags locally — zero network calls to external servers during evaluation.

Installation

Install the SDK and the cloud storage library for your provider:

# AWS
npm install @flagdrop/sdk @aws-sdk/client-s3

# GCP
npm install @flagdrop/sdk @google-cloud/storage

# Azure
npm install @flagdrop/sdk @azure/storage-blob

Only install the cloud library you need — the SDK lazy-loads providers so unused ones won't cause errors.

Quick Start

import { FlagClient } from '@flagdrop/sdk';

const flags = new FlagClient({
  bucket: 'my-app-flags',
  environment: 'production',
  provider: 'aws',       // 'aws' | 'gcp' | 'azure'
  region: 'us-east-1',
});

await flags.initialize();

// Boolean flag
const enabled = flags.getBool('new-checkout', false);

// String flag with targeting context
const theme = flags.getString('app-theme', 'light', { plan: 'enterprise' });

// Number flag
const maxItems = flags.getNumber('max-items', 10);

// JSON flag
const config = flags.getJSON('feature-config', { limit: 5 });

// Cleanup when shutting down
await flags.close();

Cloud Providers

| Provider | Install | Storage | |----------|---------|---------| | AWS | npm install @aws-sdk/client-s3 | Amazon S3 | | GCP | npm install @google-cloud/storage | Google Cloud Storage | | Azure | npm install @azure/storage-blob | Azure Blob Storage |

Each provider is loaded dynamically at runtime — only the cloud SDK you install is required.

How It Works

1. Define flags in the FlagDrop dashboard
2. FlagDrop pushes a JSON config to your cloud storage bucket
3. The SDK reads that file locally and evaluates flags at runtime

Flag evaluation happens inside your infrastructure. User context never leaves your cloud.

Targeting Rules

Pass user context to evaluate targeting rules locally:

const ui = flags.getString('checkout-ui', 'standard', {
  plan: 'enterprise',
  country: 'US',
  email: '[email protected]',
});

Supported operators: eq, neq, in, notIn, lt, gt, startsWith, endsWith.

Rules are evaluated in order — first match wins.

Typed Context & targetingKey

Context values can be strings, numbers, booleans, or string arrays. The special targetingKey field provides a stable user identifier used as a fallback for percentage rollouts:

const value = client.getBool('my-flag', false, {
  targetingKey: 'user-123',
  plan: 'enterprise',
  age: 25,
  beta: true,
  tags: ['admin', 'beta'],
});

• Numbers work directly with lt/gt operators (no string conversion needed)
• Booleans are compared via String() for eq/neq
• String arrays check overlap with in/notIn rule values
• targetingKey is used for rollout bucketing when the rollout attribute is missing from context

Percentage Rollouts

Deterministic bucketing via MurmurHash3:

const enabled = flags.getBool('new-search', false, { userId: 'user-123' });

Same user always gets the same result across evaluations and restarts.

Configuration

new FlagClient({
  bucket: 'my-flags',           // Storage bucket name (required)
  environment: 'production',     // Environment name (required)
  provider: 'aws',              // 'aws' | 'gcp' | 'azure' (required)
  region: 'us-east-1',          // Cloud region (required)
  refreshTtlMs: 30000,          // Auto-refresh interval in ms (default: 30000)
  telemetryUrl: '...',           // Optional: FlagDrop telemetry endpoint
});

Links

• FlagDrop
• Documentation
• Dashboard