FeatureHub Client SDK

2.0.2 verified Sat Apr 25 auth: no javascript

FeatureHub client/browser SDK for feature flags, remote configuration, and A/B testing. This package is designed for browser environments (or any non-Node.js context) and uses Server-Sent Events (SSE) for real-time updates. Version 2.0.2 requires Node >=20.0.0 and is TypeScript-first (ships types). Key differentiators: edge-compatible, supports catch-and-release mode for local feature flag overrides during development, integrates with React SDK via featurehub-react-sdk, and offers a client-side context for multi-environment support. Releases follow a monthly cadence.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module not supported ↓

cause Using CommonJS require() on an ESM-only package (v2+)

fix

Switch to import syntax: import { FeatureHubClient } from 'featurehub-javascript-client-sdk'

error TypeError: client.isEnabled is not a function ↓

cause Calling isEnabled on the client object instead of the repository

fix

Use repository.isEnabled('flag-key') after setting up the repository on the client.

error Error: No API key provided ↓

cause Missing or empty `apiKey` in configuration

fix

Ensure you pass apiKey as a non-empty string to newClient(), e.g., FeatureHubClient.newClient({ apiKey: '...' })

Warnings

breaking In v2.0.0, the client construction API changed from `new FeatureHubClient()` to `FeatureHubClient.newClient().build()`. Old instantiation will throw. ↓

fix Use the builder pattern: `FeatureHubClient.newClient({...}).build()`.

breaking The package became ESM-only in v2.0.0. CommonJS `require()` throws 'ERR_REQUIRE_ESM'. ↓

fix Use `import` syntax or dynamic `import()` for CommonJS projects.

gotcha `ClientFeatureRepository` events are not emitted until `client.start()` is called. Calling `repository.isEnabled()` before start returns `false` for all flags. ↓

fix Always call `client.start()` before reading features, or listen to the 'ready' event.

gotcha The `apiKey` must be a server-evaluated API key from FeatureHub; client-evaluated keys are not supported in this SDK (use the Node SDK instead). ↓

fix Ensure your FeatureHub environment is configured for server-side evaluation and use a server-sdk-api-key.

Install

npm install featurehub-javascript-client-sdk

yarn add featurehub-javascript-client-sdk

pnpm add featurehub-javascript-client-sdk

Imports

FeatureHubClient

wrong

const FeatureHubClient = require('featurehub-javascript-client-sdk')

correct

import { FeatureHubClient } from 'featurehub-javascript-client-sdk'

ESM-only package; CommonJS require() will fail. TypeScript imports are identical.

FeatureHubContext
```
import { FeatureHubContext } from 'featurehub-javascript-client-sdk'
```
Context helper for creating client instances with environment and user keys.
ClientFeatureRepository
```
import { ClientFeatureRepository } from 'featurehub-javascript-client-sdk'
```
The main repository class that stores feature states and emits events.

Quickstart

Creates a FeatureHub client with a user context, starts receiving features via SSE, and checks a boolean flag after 5 seconds.

import { FeatureHubClient, ClientFeatureRepository } from 'featurehub-javascript-client-sdk';

const repository = new ClientFeatureRepository();
const apiKey = process.env.FEATUREHUB_API_KEY ?? '';

const client = FeatureHubClient.newClient({
  apiKey,
  repository, // optional: if omitted, creates its own
  context: { // optional user context
    userKey: 'user123',
    // ... other attributes
  },
}).build();

// Listen for feature changes
repository.addListener((features) => {
  console.log('Features updated:', features);
});

// Start polling/SSE
client.start();

// Get a boolean flag
setTimeout(() => {
  const enabled = repository.isEnabled('my-feature-flag');
  console.log('Feature enabled:', enabled);
  client.stop();
}, 5000);