unleash-client

library0.0.1jsnpmunverified

The `unleash-client` package provides a server-side SDK for Node.js applications to integrate with the Unleash feature management platform. It enables dynamic evaluation of feature flags, allowing developers to control feature rollouts, perform A/B testing, and manage configurations without redeploying code. The current stable version is 6.11.1, with frequent patch and minor releases addressing bug fixes, performance improvements, and new constraint types (like semver and CIDR). This client is designed for high performance and low overhead, maintaining an in-memory repository of feature toggles that are polled from the Unleash server at regular intervals. It supports both Unleash Enterprise and Open Source instances and is suitable for applications requiring robust and scalable feature flag capabilities. Key differentiators include its focus on server-side evaluation, asynchronous initialization with event-driven readiness signals, and support for various constraint types.

devops http-networking

npm install unleash-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNLEASH-CLIENT

unleash-client

devopsjavascriptv0.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

initialize

✓ import { initialize } from 'unleash-client';

✗ const initialize = require('unleash-client').initialize;

The `initialize` function creates and configures a global Unleash instance, designed for singleton use.

UnleashClient

✓ import { UnleashClient } from 'unleash-client';

✗ const UnleashClient = require('unleash-client').UnleashClient;

Use `new UnleashClient()` for non-global instances, but generally prefer `initialize` for simplicity.

Unleash

✓ import { Unleash } from 'unleash-client';

Refers to the instantiated client object returned by `initialize()` or `new UnleashClient()`.

Demonstrates initializing the Unleash client, listening for readiness events, and evaluating a feature flag.

import { initialize } from 'unleash-client'; const unleash = initialize({ url: 'https://unleash.example.com/api', appName: 'my-node-app', instanceId: 'my-unique-instance-id', customHeaders: { Authorization: process.env.UNLEASH_API_TOKEN ?? '' }, refreshInterval: 15000 // Poll for updates every 15 seconds }); unleash.on('error', console.error); unleash.on('warn', console.warn); unleash.on('ready', () => { console.log('Unleash client is ready!'); }); unleash.on('synchronized', () => { console.log('Unleash client has synchronized with the server.'); if (unleash.isEnabled('my-feature-flag')) { console.log('Feature \'my-feature-flag\' is enabled!'); } else { console.log('Feature \'my-feature-flag\' is disabled.'); } }); // Example of usage after initialization (ensure client is ready first) setTimeout(() => { if (unleash.isEnabled('another-feature', { userId: '123' })) { console.log('Another feature is enabled for user 123.'); } else { console.log('Another feature is disabled for user 123.'); } }, 5000);

Debug

Known issues

breakingThe minimum required Node.js version is now 20. Applications running on older Node.js versions will fail to start or encounter runtime errors.

fix

Upgrade your Node.js runtime environment to version 20 or higher. Consider using a Node.js version manager like `nvm` or `volta`.

affects: >=6.0.0

gotchaBy default, `unleash-client` initializes asynchronously. Before the client has successfully synchronized with the Unleash server, all feature evaluations will return `false`. This can lead to unexpected behavior if not handled correctly.

fix

Listen for the `'ready'` or `'synchronized'` events on the Unleash client instance before evaluating feature flags. Alternatively, use a bootstrapped configuration for initial values.

affects: >=1.0.0

gotchaCalling `initialize()` multiple times will reconfigure the *global* Unleash instance. It does not create multiple distinct instances. Similarly, directly constructing `new UnleashClient()` multiple times without managing lifecycles can lead to redundant connections and increased load on the Unleash API.

fix

Ensure `initialize()` is called only once in your application's lifecycle, typically at startup. If you need multiple, distinct instances, construct `UnleashClient` directly but manage them as singletons within their respective contexts.

affects: >=1.0.0

gotchaSecurity vulnerability detected in `minimatch` dependency (CVE-2023-38546). While mitigated in version `v9.0.7`, older versions of `unleash-client` using vulnerable `minimatch` versions could be susceptible.

fix

Upgrade to `unleash-client@6.10.1` or newer to ensure the patched `minimatch` version is used. Regularly check for dependency updates.

affects: <6.10.1

breakingPrior to v6.9.4, `make-fetch-happen` was on an older dependency version. Upgrading this dependency introduced potential breaking changes due to its own major version bumps, particularly around request options or caching behaviors.

fix

Review your network configuration and any custom fetch options if upgrading from `unleash-client < 6.9.4`. Test thoroughly for unexpected network behavior.

affects: 6.9.4

Errors

Common errors & fixes

Error: Cannot find module 'unleash-client' or Cannot use import statement outside a module

Attempting to use ES module `import` syntax in a CommonJS environment without proper configuration, or the package is not installed.

fix

Ensure `unleash-client` is installed (`npm install unleash-client`). If using CommonJS, change `import { initialize } from 'unleash-client';` to `const { initialize } = require('unleash-client');`.

unleash.isEnabled is not a function

The Unleash client object (returned by `initialize` or `new UnleashClient()`) has not been correctly instantiated or is out of scope.

fix

Verify that `unleash` is a valid `UnleashClient` instance. Ensure it's correctly assigned from `initialize()` and accessible in the scope where `isEnabled` is called.

TypeError: Invalid URL

The `url` option provided to `initialize` is not a valid URL format.

fix

Ensure the `url` parameter in `initialize({ url: '...' })` is a complete and valid URL, e.g., 'https://unleash.example.com/api'.

Feature flag 'my-feature' is always disabled, even when enabled in Unleash UI.

The Unleash client might not have successfully connected and synchronized with the Unleash server, or the `appName` and `instanceId` do not match the configuration in Unleash UI.

fix

Check the client's logs for connection errors. Ensure `appName` and `instanceId` match the client registration in Unleash. Wait for the `'synchronized'` event before relying on `isEnabled()` outcomes. Verify the provided API token has client access permissions.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/Unleash/unleash-node-sdk ↗

packagehttps://www.npmjs.com/package/unleash-client ↗

homepagehttps://www.getunleash.io ↗