Native SDK @hyphen/browser-sdk

The @hyphen/browser-sdk is Hyphen's native client-side JavaScript SDK for web browsers. It provides a lightweight, optimized solution for feature flag evaluation in browser environments without requiring OpenFeature.

Installation

Install the native browser SDK:

npm install @hyphen/browser-sdk

Or include via CDN:

<script src="https://unpkg.com/@hyphen/browser-sdk@latest/dist/browser.min.js"></script>

Setup and Initialization

Initialize the Hyphen browser client with your client key and configuration:

import { HyphenBrowserClient } from '@hyphen/browser-sdk';

const client = new HyphenBrowserClient({
  apiKey: 'your-client-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 the current user:

const isEnabled = await client.isEnabled('new-ui-design', {
  userId: user.id,
  email: user.email
});

if (isEnabled) {
  // Show new UI
  renderNewUI();
} else {
  // Show legacy UI
  renderLegacyUI();
}

Real-time Flag Updates

Listen for feature flag changes in real-time:

client.on('flagsChanged', (flags) => {
  console.log('Feature flags updated:', flags);
  updateUIBasedOnFlags(flags);
});

Getting Feature Flag Details

Retrieve detailed information about a feature flag evaluation:

const flagDetails = await client.getFlagDetails('beta-features', {
  userId: user.id,
  customAttributes: {
    accountType: 'premium',
    region: 'us-west'
  }
});

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

User Context

Provide user context for targeted feature rollouts:

const context = {
  userId: 'user-789',
  email: '[email protected]',
  name: 'John Doe',
  customAttributes: {
    accountType: 'enterprise',
    betaTester: true,
    region: 'eu-west'
  }
};

const showBetaFeatures = await client.isEnabled('beta-dashboard', context);

Browser-Specific Features

The browser SDK automatically captures browser context:

// SDK automatically includes:
// - User agent
// - Screen resolution
// - Browser language
// - Timezone

const isEnabled = await client.isEnabled('mobile-optimized-view', {
  userId: user.id
});

Configuration Options

Option	Type	Required	Description
`apiKey`	`string`	Yes	Your Hyphen client API key (use client key, not server key)
`application`	`string`	Yes	The application id or alternate ID
`environment`	`string`	Yes	The environment identifier (project environment ID or alternate)
`enableTelemetry`	`boolean`	No	Enable/disable usage telemetry (default: true)
`autoUpdate`	`boolean`	No	Enable automatic flag updates (default: true)
`updateInterval`	`number`	No	Flag update interval in seconds (default: 60)

Open Feature

Installation

Install the provider and the OpenFeature server SDK:

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

Setup and Initialization

To begin using the Hyphen Provider, follow these steps:

Import the required modules.
Configure the provider with your publicKey , application 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.
Register the provider with OpenFeature.

import { OpenFeature } from '@openfeature/web-sdk';  
import { HyphenProvider, type HyphenProviderOptions } from '@hyphen/openfeature-web-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));

Use OpenFeature.setContext to configure the required context 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',  
    },  
  },  
};

OpenFeature.setContext(context);

Usage

Evaluation Context Example

Use the OpenFeature.getClient() to evaluate feature flags in your application.

const client = OpenFeature.getClient();
const isEnabled = client.getBooleanDetails('your-flag-key', false);
console.log('isEnabled', isEnabled) // true or false

Configuration

Options

Option	Type	Required	Description
`application`	`string`	Yes	The application id or alternate ID.
`environment`	`string`	Yes	The environment identifier for the Hyphen project (project environment ID or alternateId).
`horizonUrls`	`string[]`	No	Hyphen Horizon URLs for fetching flags.
`enableToggleUsage`	`boolean`	No	Enable/disable telemetry (default: true).

Context

Provide an EvaluationContext to pass contextual data for feature evaluation.

Field	Type	Required	Description
`targetingKey`	`string`	Yes	The key used for caching the evaluation response.
`ipAddress`	`string`	No	The IP address of the user making the request.
`customAttributes`	`Record<string, any>`	No	Custom attributes for additional contextual information.
`user`	`object`	No	An object containing user-specific information for the evaluation.
`user.id`	`string`	No	The unique identifier of the user.
`user.email`	`string`	No	The email address of the user.
`user.name`	`string`	No	The name of the user.
`user.customAttributes`	`Record<string, any>`	No	Custom attributes specific to the user.