Configuration

The Flagdeck JavaScript SDK offers extensive configuration options to customize its behavior for your specific application needs. This guide covers all available options and provides recommendations for different environments.

Basic Configuration

At minimum, you need to provide an API key to initialize the Flagdeck client:

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

// Initialize with minimum configuration
const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
});

All Configuration Options

Here's a comprehensive list of all available configuration options:

Option	Type	Default	Description
apiKey	string	required	Your Flagdeck API key
enableCache	boolean	true	Cache flag evaluations in memory
cacheTimeout	number	30000	Cache timeout in milliseconds (30 seconds)
timeout	number	5000	Network request timeout in milliseconds
retryConfig	object	see below	Configuration for network retry behavior
debug	boolean	false	Enable detailed logging
enableOfflineMode	boolean	false	Enable offline fallback mode
enableAnalytics	boolean	true	Track evaluation metrics
onError	function	undefined	Global error handler
defaultFlagValue	any	false	Default value when evaluation fails
sdkPlatform	string	auto-detected	Override the detected platform ('web', 'server', 'mobile')

Retry Configuration

The retryConfig object allows you to customize the retry behavior for network requests:

Option	Type	Default	Description
attempts	number	3	Maximum number of retry attempts
delay	number	1000	Initial delay in milliseconds before retrying
maxDelay	number	5000	Maximum delay between retries (with exponential backoff)

Comprehensive Example

Here's an example that demonstrates all available configuration options:

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

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

  // Caching settings
  enableCache: true,
  cacheTimeout: 60000, // 1 minute

  // Network settings
  timeout: 3000, // 3 seconds

  // Retry settings
  retryConfig: {
    attempts: 2,
    delay: 500,
    maxDelay: 2000,
  },

  // Feature settings
  enableOfflineMode: true,
  enableAnalytics: true,

  // Debug mode
  debug: process.env.NODE_ENV !== 'production',

  // Error handling
  onError: (error, flagKey) => {
    console.error(`Error evaluating flag ${flagKey}:`, error);
    // You could also log to an error tracking service here
  },

  // Default value when evaluation fails
  defaultFlagValue: false,
});

Configuration Recommendations

Browser Environments

For browser environments, we recommend:

const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  enableCache: true,
  cacheTimeout: 30000, // 30 seconds
  enableOfflineMode: true, // Helpful for unreliable connections
  timeout: 3000, // Lower timeout for better UX
  debug: false, // Disable in production
});

Server Environments (Node.js)

For server environments, we recommend:

const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  enableCache: true,
  cacheTimeout: 60000, // 1 minute - can be longer for servers
  enableOfflineMode: false, // Usually not needed for servers
  timeout: 5000, // Can be higher on servers
  retryConfig: {
    attempts: 3,
    delay: 1000,
    maxDelay: 5000,
  },
});

Mobile Environments (React Native)

For mobile applications using React Native:

const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  enableCache: true,
  cacheTimeout: 300000, // 5 minutes - longer for mobile to reduce network usage
  enableOfflineMode: true, // Critical for mobile applications
  retryConfig: {
    attempts: 2, // Fewer attempts to conserve battery
    delay: 1000,
    maxDelay: 3000,
  },
});

Runtime Configuration

While most configuration options are set during initialization, you can modify some behaviors at runtime:

Clear Cache

// Clear the evaluation cache
flagdeck.clearCache();

Flush Analytics

// Manually flush any pending analytics events
await flagdeck.flushAnalytics();

Clean Up Resources

// Clean up when the SDK is no longer needed (e.g., when your app unmounts)
await flagdeck.destroy();

Configuration Validation

The SDK validates your configuration upon initialization and will throw errors for invalid values:

• Missing API key: "API key is required"
• Cache timeout below 1000ms: "Cache timeout must be at least 1000ms"
• Request timeout below 1000ms: "Request timeout must be at least 1000ms"
• Negative retry attempts: "Retry attempts cannot be negative"
• Negative retry delay: "Retry delay cannot be negative"
• Max retry delay less than retry delay: "Max retry delay must be greater than or equal to retry delay"

Advanced Configuration

Custom Error Handling

The onError callback gives you powerful control over error handling:

const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  onError: (error, flagKey) => {
    // Log to your error tracking service
    ErrorTracker.captureException(error, {
      tags: { flagKey },
      level: 'warning'
    });

    // You can also perform custom recovery actions
    if (flagKey === 'critical-feature') {
      triggerFallbackBehavior();
    }
  }
});

Debug Logging

When debug is enabled, the SDK will output detailed logs to help with troubleshooting:

const flagdeck = new Flagdeck({
  apiKey: 'your-api-key',
  debug: true
});

// Output logs include:
// - API requests and responses
// - Cache hits and misses
// - Evaluation decisions
// - Error details
// - Performance metrics

This is particularly useful during development and testing.