Unleash Node.js Client

Common errors

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

  cause 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

  cause 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

  cause 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.

  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.
  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.

Warnings

• breaking The 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`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Upgrade to `unleash-client@6.10.1` or newer to ensure the patched `minimatch` version is used. Regularly check for dependency updates.
• breaking 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.
  Fix: Review your network configuration and any custom fetch options if upgrading from `unleash-client < 6.9.4`. Test thoroughly for unexpected network behavior.

Install

• npm install unleash-client npm
• yarn add unleash-client yarn
• pnpm add unleash-client pnpm

Imports

• initialize
  wrong:

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

  correct:

  import { initialize } from 'unleash-client';

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

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

  correct:

  import { UnleashClient } from 'unleash-client';

  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()`.

Quickstart

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);