> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getunleash.io/sdks/node/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getunleash.io/_mcp/server. # Node > Set up the Unleash Node.js SDK to evaluate feature flags with context, variants, custom strategies, events, and bootstrap. The Unleash Node.js SDK lets you evaluate feature flags in Node.js applications. It connects to Unleash or [Unleash Edge](/unleash-edge) to fetch flag configurations and evaluates them locally against an [Unleash context](/concepts/unleash-context). You can use this SDK with [Unleash Enterprise](https://www.getunleash.io/pricing) or [Unleash Open Source](https://github.com/Unleash/unleash). For an overview of how Unleash SDKs work, including offline behavior, feature compatibility across SDKs, and default refresh and metrics intervals, refer to the [SDK overview](/sdks). ## Requirements * Node.js 22.13 or later. ## Installation #### npm ```bash npm install unleash-client ``` #### yarn ```bash yarn add unleash-client ``` #### pnpm ```bash pnpm add unleash-client ``` ## Initialization Once installed, you must initialize the SDK in your application. By default, Unleash initialization is asynchronous, but if you need it to be synchronous, you can [block until the SDK has synchronized with the server](#synchronous-initialization). Note that until the SDK has synchronized with the API, all features will evaluate to `false` unless you have a [bootstrapped configuration](#bootstrap). > **Tip** > > All code samples in this section will initialize the SDK and try to connect to the > Unleash instance you point it to. You will need an Unleash instance and a > [backend token](/concepts/api-tokens-and-client-keys#backend-tokens) > for the connection to be successful. We recommend that you initialize the Unleash client SDK **as early as possible** in your application. The SDK will set up an in-memory repository and poll for updates from the Unleash server at regular intervals. ```js import { initialize } from 'unleash-client'; const unleash = initialize({ url: 'https://YOUR-API-URL', appName: 'my-node-name', customHeaders: { Authorization: '' }, }); ``` The `initialize` function will configure a **global** Unleash instance. If you call this method multiple times, the global instance will be changed. You will **not** create multiple instances. ### Check if the SDK is ready Because the SDK talks to the server in the background, it can be difficult to know exactly when it has connected and is ready to evaluate flags. If you want to run some code when the SDK becomes ready, you can listen for the `'synchronized'` event: ```js unleash.on('synchronized', () => { // the SDK has synchronized with the server // and is ready to serve }); ``` Refer to the [events reference](#events) later in this document for more information on events and an exhaustive list of all the events the SDK can emit. The `initialize` function will configure and create a *global* Unleash instance. When a global instance exists, calling this method has no effect. Call the `destroy` function to remove the globally configured instance. ### Constructing the Unleash client directly You can also construct the Unleash instance yourself instead of via the `initialize` method. When using the Unleash client directly, you **should not create new Unleash instances on every request**. Most applications are expected to only have a single Unleash instance (singleton). Each Unleash instance will maintain a connection to the Unleash API, which may result in flooding the Unleash API. ```js import { Unleash } from 'unleash-client'; const unleash = new Unleash({ url: 'https://YOUR-API-URL', appName: 'my-node-name', customHeaders: { Authorization: '' }, }); unleash.on('ready', console.log.bind(console, 'ready')); // optional error handling when using unleash directly unleash.on('error', console.error); ``` ### Synchronous initialization You can also use the `startUnleash` function and `await` to wait for the SDK to have fully synchronized with the Unleash API. This guarantees that the SDK is not operating on local and potentially stale feature flag configuration. ```js import { startUnleash } from 'unleash-client'; const unleash = await startUnleash({ url: 'https://YOUR-API-URL', appName: 'my-node-name', customHeaders: { Authorization: '' }, }); // The Unleash SDK now has a fresh state from the Unleash API const isEnabled = unleash.isEnabled('Demo'); ``` ## Check flags With the SDK initialized, you can use it to check the states of your feature flags in your application. The primary way to check feature flag status is to use the `isEnabled` method on the SDK. It takes the name of the feature and returns `true` or `false` based on whether the feature is enabled or not. ```javascript setInterval(() => { if (unleash.isEnabled('DemoToggle')) { console.log('Toggle enabled'); } else { console.log('Toggle disabled'); } }, 1000); ``` > **Note** > > In this example, we've wrapped the `isEnabled` call inside a `setInterval` function. In > the event that all your app does is start the SDK and check a feature status, this setup ensures > that the node app keeps running until the SDK has synchronized with the Unleash API. It is **not** > required in normal apps. ### Check variants You can use the `getVariant` method to retrieve the variant of a feature flag. If the flag is disabled or doesn't have any variants, the method returns the [disabled variant](/concepts/feature-flag-variants#the-disabled-variant). ```js const variant = unleash.getVariant('demo-variant'); if (variant.name === 'blue') { // do something with the blue variant... } ``` ## Unleash context Calling the `isEnabled` method with just a feature name will work in simple use cases, but in many cases you'll also want to provide an [Unleash context](/concepts/unleash-context). The SDK uses the Unleash context to evaluate any [activation strategy](/concepts/activation-strategies) with [strategy constraints](/concepts/activation-strategies#constraints), and also to evaluate some of the built-in strategies. The `isEnabled` accepts an Unleash context object as a second argument: ```js const unleashContext = { userId: '123', sessionId: 'some-session-id', remoteAddress: '127.0.0.1', properties: { region: 'EMEA', }, }; const enabled = unleash.isEnabled('someToggle', unleashContext); ``` ## Stop the client To shut down the client (turn off the polling) you can simply call the `destroy` method. This is typically not required. ```js import { destroy } from 'unleash-client'; destroy(); ``` ## TypeScript: custom feature flag names You can use TypeScript module augmentation to provide type safety for your feature flag names. This ensures that only specific feature names can be used with `isEnabled` and related methods, catching typos at compile time. ```typescript import { initialize } from 'unleash-client'; declare module 'unleash-client' { interface UnleashTypes { flagNames: 'aaa' | 'bbb'; } } const client = initialize({}); client.isEnabled('aaa'); client.isEnabled('bbb'); client.isEnabled('ccc'); // Error ``` ## Configuration options The `initialize` method takes the following arguments: * **url** - The url to fetch flags from (required). * **appName** - The application name / codebase name (required). * **environment** - The value to put in the Unleash context's `environment` property. Automatically populated in the Unleash Context (optional). This does **not** set the SDK's [Unleash environment](/concepts/environments). * **instanceId** - A unique identifier, should/could be somewhat unique. * **refreshInterval** - The poll interval to check for updates. Defaults to 15000ms. * **metricsInterval** - How often the client should send metrics to Unleash API. Defaults to 60000ms. * **strategies** - Custom activation strategies to be used. * **disableMetrics** - Disable metrics. * **customHeaders** - Provide a map(object) of custom headers to be sent to the unleash-server. * **customHeadersFunction** - Provide a function that returns a Promise resolving as custom headers to be sent to unleash-server. When options are set, this will take precedence over `customHeaders` option. * **timeout** - Specify a timeout in milliseconds for outgoing HTTP requests. Defaults to 10000ms. * **repository** - Provide a custom repository implementation to manage the underlying data. * **httpOptions** - Provide custom HTTP options such as `rejectUnauthorized` - be careful with these options as they may compromise your application security. * **namePrefix** - Only fetch feature flags with the provided name prefix. * **tags** - Only fetch feature flags tagged with the list of tags, such as: `[{type: 'simple', value: 'proxy'}]`. ## Custom strategies The client supports all [built-in activation strategies](/concepts/activation-strategies) provided by Unleash. To add a custom strategy, implement a `Strategy` subclass and pass it to the `strategies` option: ```js import { initialize, Strategy } from 'unleash-client'; class ActiveForUserWithEmailStrategy extends Strategy { constructor() { super('ActiveForUserWithEmail'); } isEnabled(parameters, context) { return parameters.emails.indexOf(context.email) !== -1; } } initialize({ url: 'http://unleash.herokuapp.com', customHeaders: { Authorization: 'API token', }, strategies: [new ActiveForUserWithEmailStrategy()], }); ``` ## Events The unleash instance object implements the EventEmitter class and **emits** the following events: | event | payload | description | | ------------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ready | - | is emitted once the fs-cache is ready. if no cache file exists it will still be emitted. The client is ready to use, but might not have synchronized with the Unleash API yet. This means the SDK still can operate on stale configurations. | | synchronized | - | is emitted when the SDK has successfully synchronized with the Unleash API, or when it has been bootstrapped, and has all the latest feature flag configuration available. | | registered | - | is emitted after the app has been registered at the API server | | sent | `object` data | key/value pair of delivered metrics | | count | `string` name, `boolean` enabled | is emitted when a feature is evaluated | | warn | `string` msg | is emitted on a warning | | error | `Error` err | is emitted on an error | | unchanged | - | is emitted each time the client gets new flag state from server, but nothing has changed | | changed | `object` data | is emitted each time the client gets new flag state from server and changes have been made | | impression | `object` data | is emitted for every user impression (isEnabled / getVariant) | Example usage: ```js import { initialize } from 'unleash-client'; const unleash = initialize({ appName: 'my-app-name', url: 'http://unleash.herokuapp.com/api/', customHeaders: { Authorization: 'API token', }, }); // Some useful life-cycle events unleash.on('ready', console.log); unleash.on('synchronized', console.log); unleash.on('error', console.error); unleash.on('warn', console.warn); unleash.once('registered', () => { // Do something after the client has registered with the server API. // Note: it might not have received updated feature flags yet. }); unleash.once('changed', () => { console.log(`Demo is enabled: ${unleash.isEnabled('Demo')}`); }); unleash.on('count', (name, enabled) => console.log(`isEnabled(${name})`)); ``` ## Impact metrics Impact metrics are lightweight, application-level time-series metrics stored and visualized directly inside Unleash. They allow you to connect specific application data, such as request counts, error rates, or memory usage, to your feature flags and release plans. Use impact metrics to validate feature impact and automate your release process. For example, you can monitor usage patterns or performance to see if a feature is meeting its goals. By combining impact metrics with release templates, you can reduce manual release operations and automate milestone progression based on metric thresholds. The SDK automatically attaches the following context labels to your metrics: `appName`, `environment`, and `origin` (for example, `origin=sdk` or `origin=Edge`). ### Counters Use counters for cumulative values that only increase, such as the total number of requests or errors. ```js const unleash = initialize({ url: 'https://YOUR-API-URL', appName: 'my-node-name', customHeaders: { Authorization: '' }, }); unleash.impactMetrics.defineCounter( 'request_count', 'Total number of HTTP requests processed' ); unleash.impactMetrics.incrementCounter('request_count'); ``` ### Gauges Use gauges for values that can go up and down, such as current memory usage or active thread count. ```js unleash.impactMetrics.defineGauge( 'heap_memory_total', 'Current heap memory usage in bytes' ); const currentHeap = process.memoryUsage().heapUsed; unleash.impactMetrics.updateGauge('heap_memory_total', currentHeap); ``` ### Histograms Use histograms to measure the distribution of values, such as request duration or response size. Unleash automatically calculates percentiles (p50, p95, p99). ```js unleash.impactMetrics.defineHistogram( 'request_time_ms', 'Time taken to process a request in milliseconds' ); const duration = 125; unleash.impactMetrics.observeHistogram('request_time_ms', duration); ``` Impact metrics are batched and sent on the same interval as regular SDK metrics. They are ingested via the regular metrics endpoint. ## Bootstrap You can bootstrap the SDK with flag configuration to evaluate flags without waiting for the Unleash API. Provide the bootstrap as inline `data`, a `url` to fetch from, or a `filePath` to load. #### Inline data ```js const client = initialize({ appName: 'my-application', url: 'https:///api/', customHeaders: { Authorization: '' }, bootstrap: { data: [ { enabled: false, name: 'BootstrapDemo', description: '', project: 'default', stale: false, type: 'release', variants: [], strategies: [{ name: 'default' }], }, ], }, }); ``` #### URL ```js const client = initialize({ appName: 'my-application', url: 'https:///api/', customHeaders: { Authorization: '' }, bootstrap: { url: 'http://localhost:3000/proxy/client/features', urlHeaders: { Authorization: 'bootstrap', }, }, }); ``` #### File ```js const client = initialize({ appName: 'my-application', url: 'https:///api/', customHeaders: { Authorization: '' }, bootstrap: { filePath: '/tmp/some-bootstrap.json', }, }); ``` ## Flag definitions Sometimes you might be interested in the raw feature flag definitions. ```js import { initialize, getFeatureToggleDefinition, getFeatureToggleDefinitions, } from 'unleash-client'; initialize({ url: 'http://unleash.herokuapp.com/api/', customHeaders: { Authorization: '' }, appName: 'my-app-name', instanceId: 'my-unique-instance-id', }); const featureToggleX = getFeatureToggleDefinition('app.ToggleX'); const featureToggles = getFeatureToggleDefinitions(); ``` ## Custom store provider (Available from v3.11.x) By default, this SDK will use a store provider that writes a backup of the feature flag configuration to a **file on disk**. This happens every time it receives updated configuration from the Unleash API. You can swap out the store provider with either the provided in-memory store provider or a custom store provider implemented by you. ### Use `InMemStorageProvider` ```js import { initialize, InMemStorageProvider } from 'unleash-client'; const client = initialize({ appName: 'my-application', url: 'http://localhost:3000/api/', customHeaders: { Authorization: '' }, storageProvider: new InMemStorageProvider(), }); ``` ### Custom store provider backed by Redis ```js import { initialize, InMemStorageProvider } from 'unleash-client'; import { createClient } from 'redis'; class CustomRedisStore { async set(key, data) { const client = createClient(); await client.connect(); await client.set(key, JSON.stringify(data)); } async get(key) { const client = createClient(); await client.connect(); const data = await client.get(key); return JSON.parse(data); } } const client = initialize({ appName: 'my-application', url: 'http://localhost:3000/api/', customHeaders: { Authorization: 'my-key', }, storageProvider: new CustomRedisStore(), }); ``` ## Custom repository You can manage the underlying data layer yourself if you want to. This enables you to use Unleash offline, from a browser environment, or by implement your own caching layer. See [example](https://github.com/Unleash/unleash-node-sdk/blob/main/examples/custom_repository.js). Unleash depends on a `ready` event of the repository you pass in. Be sure that you emit the event **after** you've initialized Unleash. ## Outbound network proxy You can connect to the Unleash API through the corporate proxy by setting one of the environment variables: `HTTP_PROXY` or `HTTPS_PROXY`. > Set up the Unleash Node.js SDK to evaluate feature flags with context, variants, custom strategies, events, and bootstrap.