{"id":12310,"library":"unleash-client","title":"Unleash Node.js Client","description":"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.","status":"active","version":"6.10.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/Unleash/unleash-node-sdk","tags":["javascript","unleash","client","feature toggle","typescript"],"install":[{"cmd":"npm install unleash-client","lang":"bash","label":"npm"},{"cmd":"yarn add unleash-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add unleash-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `initialize` function creates and configures a global Unleash instance, designed for singleton use.","wrong":"const initialize = require('unleash-client').initialize;","symbol":"initialize","correct":"import { initialize } from 'unleash-client';"},{"note":"Use `new UnleashClient()` for non-global instances, but generally prefer `initialize` for simplicity.","wrong":"const UnleashClient = require('unleash-client').UnleashClient;","symbol":"UnleashClient","correct":"import { UnleashClient } from 'unleash-client';"},{"note":"Refers to the instantiated client object returned by `initialize()` or `new UnleashClient()`.","symbol":"Unleash","correct":"import { Unleash } from 'unleash-client';"}],"quickstart":{"code":"import { initialize } from 'unleash-client';\n\nconst unleash = initialize({\n  url: 'https://unleash.example.com/api',\n  appName: 'my-node-app',\n  instanceId: 'my-unique-instance-id',\n  customHeaders: { Authorization: process.env.UNLEASH_API_TOKEN ?? '' },\n  refreshInterval: 15000 // Poll for updates every 15 seconds\n});\n\nunleash.on('error', console.error);\nunleash.on('warn', console.warn);\nunleash.on('ready', () => {\n  console.log('Unleash client is ready!');\n});\nunleash.on('synchronized', () => {\n  console.log('Unleash client has synchronized with the server.');\n  if (unleash.isEnabled('my-feature-flag')) {\n    console.log('Feature \\'my-feature-flag\\' is enabled!');\n  } else {\n    console.log('Feature \\'my-feature-flag\\' is disabled.');\n  }\n});\n\n// Example of usage after initialization (ensure client is ready first)\nsetTimeout(() => {\n  if (unleash.isEnabled('another-feature', { userId: '123' })) {\n    console.log('Another feature is enabled for user 123.');\n  } else {\n    console.log('Another feature is disabled for user 123.');\n  }\n}, 5000);","lang":"typescript","description":"Demonstrates initializing the Unleash client, listening for readiness events, and evaluating a feature flag."},"warnings":[{"fix":"Upgrade your Node.js runtime environment to version 20 or higher. Consider using a Node.js version manager like `nvm` or `volta`.","message":"The minimum required Node.js version is now 20. Applications running on older Node.js versions will fail to start or encounter runtime errors.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Calling `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `unleash-client@6.10.1` or newer to ensure the patched `minimatch` version is used. Regularly check for dependency updates.","message":"Security 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.","severity":"gotcha","affected_versions":"<6.10.1"},{"fix":"Review your network configuration and any custom fetch options if upgrading from `unleash-client < 6.9.4`. Test thoroughly for unexpected network behavior.","message":"Prior 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.","severity":"breaking","affected_versions":"6.9.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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');`.","cause":"Attempting to use ES module `import` syntax in a CommonJS environment without proper configuration, or the package is not installed.","error":"Error: Cannot find module 'unleash-client' or Cannot use import statement outside a module"},{"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.","cause":"The Unleash client object (returned by `initialize` or `new UnleashClient()`) has not been correctly instantiated or is out of scope.","error":"unleash.isEnabled is not a function"},{"fix":"Ensure the `url` parameter in `initialize({ url: '...' })` is a complete and valid URL, e.g., 'https://unleash.example.com/api'.","cause":"The `url` option provided to `initialize` is not a valid URL format.","error":"TypeError: Invalid URL"},{"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.","cause":"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.","error":"Feature flag 'my-feature' is always disabled, even when enabled in Unleash UI."}],"ecosystem":"npm"}