The @hyphen/sdk is Hyphen's native server-side Node.js SDK for feature flag evaluation and management. It provides a streamlined, purpose-built interface for backend services, APIs, and server-rendered applications without requiring OpenFeature.

Table of Contents

• • Installation
  • Setup and Initialization
  • Usage
    • Basic Feature Flag Evaluation
    • Getting Feature Flag Details
    • Targeting Context
  • Configuration Options
• Open Feature
  • Installation
  • Setup and Initialization
  • Usage
    • Evaluation Context Example
  • Configuration
    • Options
    • Cache Configuration
    • Context
  • Example

Installation

Install the native SDK:

npm install @hyphen/sdk

Setup and Initialization

Initialize the Hyphen client with your API key and configuration:

import { HyphenClient } from '@hyphen/sdk';

const client = new HyphenClient({
  apiKey: 'your-api-key',
  application: 'your-application-name',
  environment: 'production' // or project environment ID
});

await client.initialize();

Usage

Basic Feature Flag Evaluation

Check if a feature is enabled for a user:

const isEnabled = await client.isEnabled('new-checkout-flow', {
  userId: 'user-123',
  email: '[email protected]'
});

if (isEnabled) {
  // Execute new checkout flow
  processNewCheckout();
} else {
  // Use legacy checkout
  processLegacyCheckout();
}

Getting Feature Flag Details

Retrieve detailed information about a feature flag evaluation:

const flagDetails = await client.getFlagDetails('feature-flag-key', {
  userId: 'user-123',
  customAttributes: {
    subscriptionLevel: 'premium',
    region: 'us-east'
  }
});

console.log(flagDetails.enabled); // true or false
console.log(flagDetails.variant); // variant name if applicable
console.log(flagDetails.metadata); // additional flag metadata

Targeting Context

Provide rich context for advanced targeting rules:

const context = {
  userId: 'user-456',
  email: '[email protected]',
  name: 'Jane Smith',
  ipAddress: '203.0.113.42',
  customAttributes: {
    role: 'admin',
    subscriptionLevel: 'enterprise',
    region: 'us-west'
  }
};

const showAdminPanel = await client.isEnabled('admin-panel-v2', context);

Configuration Options

Open Feature

The Hyphen Toggle Provider for Node.js is an OpenFeature provider implementation that enables seamless feature flag evaluation. This section covers setup, usage, and configuration specific to the JavaScript implementation.

Installation

Install the provider and the OpenFeature server SDK:

npm install @openfeature/server-sdk @hyphen/openfeature-server-provider

Setup and Initialization

To begin using the Hyphen Provider, follow these steps:

1. Import the required modules.

2. Configure the provider with your publicKey , application name and environment.
   You can specify the environment in one of two formats:

   • Alternate ID (e.g., "production", "staging") — the environment in which your application is running.
   • Project Environment ID (e.g., pevr_abc123) — useful for internal references.

3. Register the provider with OpenFeature.

import { OpenFeature } from '@openfeature/server-sdk';  
import { HyphenProvider, type HyphenProviderOptions } from '@hyphen/openfeature-server-provider';

const publicKey = "your-public-key-here";

const options: HyphenProviderOptions = {
  application: 'your-application-name',
  environment: 'production', // or project environment ID
};

await OpenFeature.setProviderAndWait(new HyphenProvider(publicKey, options));

4. Configure the context needed for feature targeting evaluations, incorporating user or application context.

const context: HyphenEvaluationContext = {  
  targetingKey: 'user-123',  
  ipAddress: '203.0.113.42',  
  customAttributes: {  
    subscriptionLevel: 'premium',  
    region: 'us-east',  
  },  
  user: {  
    id: 'user-123',  
    email: '[email protected]',  
    name: 'John Doe',  
    customAttributes: {  
      role: 'admin',  
    },  
  },  
};

Usage

Evaluation Context Example

Evaluate a feature flag using the OpenFeature client and context information:

const client = OpenFeature.getClient();
const flagDetailsWithContext = await client.getBooleanDetails('feature-flag-key', false, context);

console.log(flagDetailsWithContext.value); // true or false

Configuration

Options

Cache Configuration

The cache option accepts the following properties:

Example with cache configuration:

const options: HyphenProviderOptions = {
  application: 'your-application-name',
  environment: 'production',
  cache: {
    ttlSeconds: 600, // 10 minutes
    generateCacheKeyFn: (context: HyphenEvaluationContext) => {
      return `${context.targetingKey}-${context.user?.id}`;
    },
  },
};

Context

Provide an EvaluationContext to pass contextual data for feature evaluation.

Example

const context: HyphenEvaluationContext = {  
  targetingKey: 'user-456',  
  customAttributes: {  
    subscriptionLevel: 'premium',  
  },  
};

const flagDetails = await client.getBooleanDetails('enable-discounts', false, context);

if (flagDetails.value) {  
  console.log('Discounts enabled for premium users.');  
} else {  
  console.log('No discounts available.');  
}