@hyphen/browser-sdk

v1.1.2

Published

a month ago

Hyphen SDK for Browser / Javascript

0High
0Medium
0Low

hyphen sdk browser react vue vuejs svelt javascript typescript

Hyphen Browser SDK

The Hyphen Browser SDK is used as a base library to get evaluations and works for browsers and the base for javascript libraries such as react, vuejs, svelte, etc . For the full featured nodejs sdk use @hyphen/sdk

Installation

Install the package using npm, yarn, or pnpm:

npm install @hyphen/browser-sdk

For browser usage via CDN:

<script src="https://cdn.jsdelivr.net/npm/@hyphen/browser-sdk@latest/dist/index.browser.js"></script>

Usage

Basic Setup

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

// Initialize the Toggle client
const toggle = new Toggle({
  publicApiKey: 'public_your-api-key-here',
  applicationId: 'your-app-id',
  environment: 'production', // or 'development'
  defaultContext: {
    targetingKey: 'user-123',
    user: {
      id: 'user-123',
      email: '[email protected]',
      name: 'John Doe'
    }
  }
});

Using Helper Methods

The SDK provides type-safe helper methods for common data types:

Boolean Toggles

const isFeatureEnabled = await toggle.getBoolean('feature-flag', false);
if (isFeatureEnabled) {
  console.log('Feature is enabled!');
}

String Toggles

const welcomeMessage = await toggle.getString('welcome-message', 'Hello World');
document.getElementById('welcome').textContent = welcomeMessage;

Number Toggles

const maxRetries = await toggle.getNumber('max-retries', 3);
const timeout = await toggle.getNumber('api-timeout', 5000);

Object Toggles

const config = await toggle.getObject('app-config', { theme: 'light' });
console.log('App configuration:', config);

Using the Generic `get()` Method

// Generic method with type parameter
const feature = await toggle.get<boolean>('feature-toggle', false);
const settings = await toggle.get<object>('user-settings', {});

Context Override

You can override the default context for specific evaluations:

const customContext = {
  targetingKey: 'special-user',
  user: { id: 'special-user', plan: 'premium' },
  customAttributes: { region: 'us-west' }
};

const result = await toggle.getBoolean('premium-feature', false, {
  context: customContext
});

Error Handling and Events

The Toggle client extends Hookified, so it exposes a standard event-emitter surface. Toggle evaluation errors are swallowed by design (the SDK falls back to your defaultValue) and re-emitted on the ToggleEvents.Error event so you can observe them without breaking the caller.

import { Toggle, ToggleEvents } from '@hyphen/browser-sdk';

const toggle = new Toggle({
  publicApiKey: 'public_your-api-key-here',
  applicationId: 'your-app-id',
});

toggle.on(ToggleEvents.Error, (error) => {
  console.error('Toggle evaluation failed:', error);
});

// Still returns `false` on failure — the listener above also fires.
const isFeatureEnabled = await toggle.getBoolean('feature-flag', false);

You can use once, off, and removeAllListeners as you would with any Node-style event emitter.

Browser Integration Example

Using ES Modules

<!DOCTYPE html>
<html>
<head>
  <title>Hyphen Toggle Example</title>
</head>
<body>
  <div id="feature-content" style="display: none;">
    <h2>Premium Feature</h2>
    <p>This content is only shown when the feature is enabled!</p>
  </div>

  <script type="module">
    import { Toggle } from '@hyphen/browser-sdk';

    const toggle = new Toggle({
      publicApiKey: 'public_your-api-key-here',
      applicationId: 'your-app-id',
      defaultContext: {
        targetingKey: 'anonymous-user',
        customAttributes: {
          plan: 'free'
        }
      }
    });

    // Check if premium feature is enabled
    const isPremiumEnabled = await toggle.getBoolean('premium-feature', false);
    
    if (isPremiumEnabled) {
      document.getElementById('feature-content').style.display = 'block';
    }

    // Dynamic configuration
    const theme = await toggle.getString('app-theme', 'light');
    document.body.className = `theme-${theme}`;
  </script>
</body>
</html>

Using jsDelivr CDN

<!DOCTYPE html>
<html>
<head>
  <title>Hyphen Toggle Example</title>
  <script src="https://cdn.jsdelivr.net/npm/@hyphen/browser-sdk@latest/dist/index.browser.js"></script>
</head>
<body>
  <div id="feature-content" style="display: none;">
    <h2>Premium Feature</h2>
    <p>This content is only shown when the feature is enabled!</p>
  </div>

  <script>
    // HyphenBrowserSDK is available as a global variable
    const { Toggle } = HyphenBrowserSDK;

    const toggle = new Toggle({
      publicApiKey: 'public_your-api-key-here',
      applicationId: 'your-app-id',
      defaultContext: {
        targetingKey: 'anonymous-user',
        customAttributes: {
          plan: 'free'
        }
      }
    });

    // Use async function for top-level await support
    (async () => {
      // Check if premium feature is enabled
      const isPremiumEnabled = await toggle.getBoolean('premium-feature', false);
      
      if (isPremiumEnabled) {
        document.getElementById('feature-content').style.display = 'block';
      }

      // Dynamic configuration
      const theme = await toggle.getString('app-theme', 'light');
      document.body.className = `theme-${theme}`;
    })();
  </script>
</body>
</html>

API Reference

Constructor Options

publicApiKey (string): Your Hyphen public API key
applicationId (string): Your application identifier
environment (string, optional): Environment name (default: 'development')
defaultContext (ToggleContext, optional): Default evaluation context
horizonUrls (string[], optional): Custom Horizon endpoint URLs
defaultTargetKey (string, optional): Default targeting key

Helper Methods

getBoolean(toggleKey, defaultValue, options?) - Get boolean toggle
getString(toggleKey, defaultValue, options?) - Get string toggle
getNumber(toggleKey, defaultValue, options?) - Get number toggle
getObject<T>(toggleKey, defaultValue, options?) - Get object toggle
get<T>(toggleKey, defaultValue, options?) - Generic toggle getter

Contributing

We welcome contributions to the Hyphen Node.js SDK! If you have an idea for a new feature, bug fix, or improvement, please follow the Contribution guidelines and our Code of Conduct.