Getting Started

Official JavaScript/TypeScript SDK for Flagdeck, a modern feature flag and feature management system.

Installation

Install the Flagdeck SDK using npm or yarn:

# Using npm
npm install @flagdeck/js

# Using yarn
yarn add @flagdeck/js

Quick Start

import { Flagdeck } from '@flagdeck/js';

// Initialize the client
const flagdeck = new Flagdeck({
  apiKey: 'your-api-key'
});

// Check if a feature flag is enabled
async function checkFeature() {
  const isEnabled = await flagdeck.isEnabled('new-feature', {
    userId: 'user-123',
    attributes: {
      country: 'US',
      plan: 'premium'
    }
  });

  if (isEnabled) {
    // Feature is enabled for this user
    enableNewFeature();
  } else {
    // Feature is disabled
    useDefaultFeature();
  }
}

Environment-Specific Usage

The SDK automatically detects your environment (browser or Node.js) and uses the appropriate implementation. However, you can also explicitly import the version you need:

Browser-Specific Import

For browser applications (including React, Vue, Angular, etc.):

// Import browser-specific implementation
import { Flagdeck } from '@flagdeck/js/browser';

const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  // Browser-specific options
  enableOfflineMode: true // Uses localStorage for offline storage
});

Node.js-Specific Import

For server applications (Node.js):

// Import Node.js-specific implementation
import { Flagdeck } from '@flagdeck/js/node';

const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  // Node.js-specific options
  enableOfflineMode: true // Uses filesystem for offline storage
});

Basic Usage

The Flagdeck SDK provides several methods to work with feature flags:

Checking Boolean Flags

The most common use case is checking if a feature flag is enabled:

// Simple check with no context
const isEnabled = await flagdeck.isEnabled('new-feature');

// Check with user context
const isEnabledForUser = await flagdeck.isEnabled('new-feature', {
  userId: 'user-123'
});

// Check with detailed context
const isEnabledWithContext = await flagdeck.isEnabled('new-feature', {
  userId: 'user-456',
  attributes: {
    country: 'CA',
    userType: 'admin'
  }
});

Getting Flag Values

For flags with non-boolean values, use the getValue method:

// Get a string value
const variant = await flagdeck.getValue('experiment-group', context, 'control');

// Get a numeric value
const limit = await flagdeck.getValue('api-rate-limit', context, 100);

// Get an object
const config = await flagdeck.getValue('service-config', context, {
  timeout: 5000,
  retries: 3
});

Evaluating Multiple Flags

For better performance, evaluate multiple flags in a single request:

const values = await flagdeck.getValues([
  'feature-a',
  'feature-b',
  'rate-limit'
], context);

console.log(values['feature-a']); // boolean
console.log(values['rate-limit']); // number

Key Concepts

Evaluation Context

The context object lets you provide user and environment information for targeting rules:

const context = {
  // Unique user identifier (strongly recommended)
  userId: 'user-123',

  // Optional session identifier
  sessionId: 'session-abc',

  // Custom attributes for targeting rules
  attributes: {
    email: '[email protected]',
    country: 'US',
    plan: 'premium',
    deviceType: 'mobile'
  }
};

Configuration Options

The SDK accepts various configuration options when initializing:

const flagdeck = new Flagdeck({
  // Required: Your API key from the Flagdeck dashboard
  apiKey: 'your-api-key',

  // Optional: Enable caching (default: true)
  enableCache: true,

  // Optional: Cache timeout in milliseconds (default: 30000)
  cacheTimeout: 60000,

  // Optional: Enable debug logging (default: false)
  debug: true,
  
  // Optional: Enable offline mode (default: false)
  enableOfflineMode: false,
  
  // Optional: Enable analytics (default: true)
  enableAnalytics: true,
  
  // Optional: Request timeout in milliseconds (default: 5000)
  timeout: 5000,
  
  // Optional: Retry configuration
  retryConfig: {
    attempts: 3,
    delay: 1000,
    maxDelay: 5000
  },
  
  // Optional: Global error handler
  onError: (error, flagKey) => {
    console.error(`Error evaluating flag ${flagKey}:`, error);
  },
  
  // Optional: Default value when evaluation fails
  defaultFlagValue: false
});

Environment-Specific Features

Browser-Specific Features

When using the SDK in a browser environment:

• Offline Storage: Uses localStorage for storing flag values when offline mode is enabled
• Context Enrichment: Automatically collects browser information (browser name, version, screen size, etc.)
• Performance: Optimized for browser runtime with minimal dependencies

// Browser-specific offline storage example
const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  enableOfflineMode: true
});

// Save flag for offline use (uses localStorage in browsers)
await flagdeck.saveForOffline('feature-a', true);

Node.js-Specific Features

When using the SDK in a Node.js environment:

• Offline Storage: Uses filesystem storage (in user's home directory) when offline mode is enabled
• Context Enrichment: Automatically collects Node.js information (version, platform, environment)
• Compatibility: Works with Node.js 14+ (automatically uses node-fetch if needed)

// Node.js-specific offline storage example
const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  enableOfflineMode: true
});

// Save flag for offline use (uses filesystem in Node.js)
await flagdeck.saveForOffline('feature-a', true);

Next Steps

• Learn more about Value Types
• Explore Evaluation Context in depth
• Set up Error Handling
• Implement Middleware
• Enable Offline Mode
• Browse the complete API Reference