{"id":30064533,"url":"https://github.com/Unleash/unleash-node-sdk","last_synced_at":"2025-08-08T05:04:30.839Z","repository":{"id":27837649,"uuid":"31327686","full_name":"Unleash/unleash-node-sdk","owner":"Unleash","description":"Unleash client SDK for Node.js","archived":false,"fork":false,"pushed_at":"2025-07-31T11:33:27.000Z","size":3787,"stargazers_count":221,"open_issues_count":18,"forks_count":71,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-08-01T20:49:49.484Z","etag":null,"topics":["client-sdk","feature-flags","feature-management","feature-toggles","hacktoberfest","javascript","nodejs","toggles","unleash-server"],"latest_commit_sha":null,"homepage":"https://docs.getunleash.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Unleash.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-02-25T17:58:31.000Z","updated_at":"2025-07-31T11:24:04.000Z","dependencies_parsed_at":"2023-12-17T23:26:42.852Z","dependency_job_id":"1b2a51f4-e9ed-4aa1-bf94-b8230cf0a716","html_url":"https://github.com/Unleash/unleash-node-sdk","commit_stats":{"total_commits":682,"total_committers":56,"mean_commits":"12.178571428571429","dds":0.68475073313783,"last_synced_commit":"9b860b74080b65a225d34c54f3f51e548755e2da"},"previous_names":["unleash/unleash-node-sdk","unleash/unleash-client-node"],"tags_count":137,"template":false,"template_full_name":null,"purl":"pkg:github/Unleash/unleash-node-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-node-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-node-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-node-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-node-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Unleash","download_url":"https://codeload.github.com/Unleash/unleash-node-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unleash%2Funleash-node-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269366853,"owners_count":24405250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-sdk","feature-flags","feature-management","feature-toggles","hacktoberfest","javascript","nodejs","toggles","unleash-server"],"created_at":"2025-08-08T05:03:11.807Z","updated_at":"2025-08-08T05:04:30.825Z","avatar_url":"https://github.com/Unleash.png","language":"TypeScript","readme":"# Unleash Client SDK for Node.js\n\n[![Unleash node SDK on npm](https://img.shields.io/npm/v/unleash-client)](https://www.npmjs.com/package/unleash-client)\n![npm downloads](https://img.shields.io/npm/dm/unleash-client)\n[![Build Status](https://github.com/Unleash/unleash-node-sdk/actions/workflows/build-and-test.yaml/badge.svg)](https://github.com/Unleash/unleash-node-sdk/actions)\n[![Code Climate](https://codeclimate.com/github/Unleash/unleash-node-sdk/badges/gpa.svg)](https://codeclimate.com/github/Unleash/unleash-node-sdk)\n[![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-node-sdk/badge.svg?branch=main)](https://coveralls.io/github/Unleash/unleash-node-sdk?branch=main)\n\nUnleash is a private, secure, and scalable [feature management platform](https://www.getunleash.io/)\nbuilt to reduce the risk of releasing new features and accelerate software development. This\nserver-side Node.js SDK is designed to help you integrate with Unleash and evaluate feature flags\ninside your application.\n\nYou can use this client with\n[Unleash Enterprise](https://www.getunleash.io/pricing?utm_source=readme\u0026utm_medium=nodejs) or\n[Unleash Open Source](https://github.com/Unleash/unleash).\n\n## Getting started\n\n### 1. Install the Unleash client in your project\n\n```bash\nnpm install unleash-client\n```\n\nor\n\n```bash\nyarn add unleash-client\n```\n\n(Or any other tool you like.)\n\n### 2. Initialize `unleash-client`\n\nOnce installed, you must initialize the SDK in your application. By default, Unleash initialization\nis asynchronous, but if you need it to be synchronous, you can\n[block until the SDK has synchronized with the server](#synchronous-initialization).\n\nNote that until the SDK has synchronized with the API, all features will evaluate to `false` unless\nyou have a [bootstrapped configuration](#bootstrap).\n\n---\n\n💡 **Tip**: All code samples in this section will initialize the SDK and try to connect to the\nUnleash instance you point it to. You will need an Unleash instance and a\n[server-side API token](https://docs.getunleash.io/reference/api-tokens-and-client-keys#client-tokens)\nfor the connection to be successful.\n\n---\n\nWe recommend that you initialize the Unleash client SDK **as early as possible** in your\napplication. The SDK will set up an in-memory repository and poll for updates from the Unleash\nserver at regular intervals.\n\n```js\nimport { initialize } from 'unleash-client';\n\nconst unleash = initialize({\n  url: 'https://YOUR-API-URL',\n  appName: 'my-node-name',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n});\n```\n\nThe `initialize` function will configure a **global** Unleash instance. If you call this method\nmultiple times, the global instance will be changed. You will **not** create multiple instances.\n\n#### How do I know when it's ready?\n\nBecause the SDK takes care of talking to the server in the background, it can be difficult to know\nexactly when it has connected and is ready to evaluate toggles. If you want to run some code when\nthe SDK becomes ready, you can listen for the `'synchronized'` event:\n\n```js\nunleash.on('synchronized', () =\u003e {\n  // the SDK has synchronized with the server\n  // and is ready to serve\n});\n```\n\nRefer to the [events reference](#events) later in this document for more information on events and\nan exhaustive list of all the events the SDK can emit.\n\nThe `initialize` function will configure and create a _global_ Unleash instance. When a global\ninstance exists, calling this method has no effect. Call the `destroy` function to remove the\nglobally configured instance.\n\n#### Constructing the Unleash client directly\n\nYou can also construct the Unleash instance yourself instead of via the `initialize` method.\n\nWhen using the Unleash client directly, you **should not create new Unleash instances on every\nrequest**. Most applications are expected to only have a single Unleash instance (singleton). Each\nUnleash instance will maintain a connection to the Unleash API, which may result in flooding the\nUnleash API.\n\n```js\nimport { Unleash } from 'unleash-client';\n\nconst unleash = new Unleash({\n  url: 'https://YOUR-API-URL',\n  appName: 'my-node-name',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n});\n\nunleash.on('ready', console.log.bind(console, 'ready'));\n\n// optional error handling when using unleash directly\nunleash.on('error', console.error);\n```\n\n#### Synchronous initialization\n\nYou can also use the `startUnleash` function and `await` to wait for the SDK to have fully\nsynchronized with the Unleash API. This guarantees that the SDK is not operating on local and\npotentially stale feature toggle configuration.\n\n```js\nimport { startUnleash } from 'unleash-client';\n\nconst unleash = await startUnleash({\n  url: 'https://YOUR-API-URL',\n  appName: 'my-node-name',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n});\n\n// The Unleash SDK now has a fresh state from the Unleash API\nconst isEnabled = unleash.isEnabled('Demo');\n```\n\n### 3. Check features\n\nWith the SDK initialized, you can use it to check the states of your feature toggles in your\napplication.\n\nThe primary way to check feature toggle status is to use the `isEnabled` method on the SDK. It takes\nthe name of the feature and returns `true` or `false` based on whether the feature is enabled or\nnot.\n\n```javascript\nsetInterval(() =\u003e {\n  if (unleash.isEnabled('DemoToggle')) {\n    console.log('Toggle enabled');\n  } else {\n    console.log('Toggle disabled');\n  }\n}, 1000);\n```\n\n👀 **Note**: In this example, we've wrapped the `isEnabled` call inside a `setInterval` function. In\nthe event that all your app does is start the SDK and check a feature status, this setup ensures\nthat the node app keeps running until the SDK has synchronized with the Unleash API. It is **not**\nrequired in normal apps.\n\n#### Check variants\n\nYou can use the `getVariant` method to retrieve the variant of a feature flag. If the flag is\ndisabled or doesn't have any variants, the method returns the\n[disabled variant](https://docs.getunleash.io/reference/feature-toggle-variants#the-disabled-variant).\n\n```js\nconst variant = unleash.getVariant('demo-variant');\n\nif (variant.name === 'blue') {\n  // do something with the blue variant...\n}\n```\n\n#### Providing an Unleash context\n\nCalling the `isEnabled` method with just a feature name will work in simple use cases, but in many\ncases you'll also want to provide an\n[Unleash context](https://docs.getunleash.io/reference/unleash-context). The SDK uses the Unleash\ncontext to evaluate any\n[activation strategy](https://docs.getunleash.io/reference/activation-strategies) with\n[strategy constraints](https://docs.getunleash.io/reference/strategy-constraints), and also to\nevaluate some of the built-in strategies.\n\nThe `isEnabled` accepts an Unleash context object as a second argument:\n\n```js\nconst unleashContext = {\n  userId: '123',\n  sessionId: 'some-session-id',\n  remoteAddress: '127.0.0.1',\n  properties: {\n    region: 'EMEA',\n  },\n};\n\nconst enabled = unleash.isEnabled('someToggle', unleashContext);\n```\n\n### 4. Stop unleash\n\nTo shut down the client (turn off the polling) you can simply call the `destroy` method. This is\ntypically not required.\n\n```js\nimport { destroy } from 'unleash-client';\ndestroy();\n```\n\n### Built-in activation strategies\n\nThe client supports all built-in activation strategies provided by Unleash.\n\nRead more about\n[activation strategies in the official docs](https://docs.getunleash.io/reference/activation-strategies).\n\n### Unleash context\n\nIn order to use some of the common activation strategies you must provide an\n[Unleash context](https://docs.getunleash.io/reference/unleash-context). This client SDK allows you\nto send in the unleash context as part of the `isEnabled` call:\n\n```javascript\nconst unleashContext = {\n  userId: '123',\n  sessionId: 'some-session-id',\n  remoteAddress: '127.0.0.1',\n};\nunleash.isEnabled('someToggle', unleashContext);\n```\n\n## Advanced usage\n\nThe initialize method takes the following arguments:\n\n- **url** - The url to fetch toggles from (required).\n- **appName** - The application name / codebase name (required).\n- **environment** - The value to put in the Unleash context's `environment` property. Automatically\n  populated in the Unleash Context (optional). This does **not** set the SDK's\n  [Unleash environment](https://docs.getunleash.io/reference/environments).\n- **instanceId** - A unique identifier, should/could be somewhat unique.\n- **refreshInterval** - The poll interval to check for updates. Defaults to 15000ms.\n- **metricsInterval** - How often the client should send metrics to Unleash API. Defaults to\n  60000ms.\n- **strategies** - Custom activation strategies to be used.\n- **disableMetrics** - Disable metrics.\n- **customHeaders** - Provide a map(object) of custom headers to be sent to the unleash-server.\n- **customHeadersFunction** - Provide a function that returns a Promise resolving as custom headers\n  to be sent to unleash-server. When options are set, this will take precedence over `customHeaders`\n  option.\n- **timeout** - Specify a timeout in milliseconds for outgoing HTTP requests. Defaults to 10000ms.\n- **repository** - Provide a custom repository implementation to manage the underlying data.\n- **httpOptions** - Provide custom HTTP options such as `rejectUnauthorized` - be careful with these\n  options as they may compromise your application security.\n- **namePrefix** - Only fetch feature toggles with the provided name prefix.\n- **tags** - Only fetch feature toggles tagged with the list of tags, such as:\n  `[{type: 'simple', value: 'proxy'}]`.\n\n## Custom strategies\n\n### 1. Implement the custom strategy\n\n```js\nimport { initialize, Strategy } from 'unleash-client';\nclass ActiveForUserWithEmailStrategy extends Strategy {\n  constructor() {\n    super('ActiveForUserWithEmail');\n  }\n\n  isEnabled(parameters, context) {\n    return parameters.emails.indexOf(context.email) !== -1;\n  }\n}\n```\n\n### 2. Register your custom strategy\n\n```js\ninitialize({\n  url: 'http://unleash.herokuapp.com',\n  customHeaders: {\n    Authorization: 'API token',\n  },\n  strategies: [new ActiveForUserWithEmailStrategy()],\n});\n```\n\n## Events\n\nThe unleash instance object implements the EventEmitter class and **emits** the following events:\n\n| event        | payload                          | description                                                                                                                                                                                                                                  |\n| ------------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 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. |\n| 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 toggle configuration available.                                                                 |\n| registered   | -                                | is emitted after the app has been registered at the API server                                                                                                                                                                               |\n| sent         | `object` data                    | key/value pair of delivered metrics                                                                                                                                                                                                          |\n| count        | `string` name, `boolean` enabled | is emitted when a feature is evaluated                                                                                                                                                                                                       |\n| warn         | `string` msg                     | is emitted on a warning                                                                                                                                                                                                                      |\n| error        | `Error` err                      | is emitted on an error                                                                                                                                                                                                                       |\n| unchanged    | -                                | is emitted each time the client gets new toggle state from server, but nothing has changed                                                                                                                                                   |\n| changed      | `object` data                    | is emitted each time the client gets new toggle state from server and changes have been made                                                                                                                                                 |\n| impression   | `object` data                    | is emitted for every user impression (isEnabled / getVariant)                                                                                                                                                                                |\n\nExample usage:\n\n```js\nimport { initialize } from 'unleash-client';\n\nconst unleash = initialize({\n  appName: 'my-app-name',\n  url: 'http://unleash.herokuapp.com/api/',\n  customHeaders: {\n    Authorization: 'API token',\n  },\n});\n\n// Some useful life-cycle events\nunleash.on('ready', console.log);\nunleash.on('synchronized', console.log);\nunleash.on('error', console.error);\nunleash.on('warn', console.warn);\n\nunleash.once('registered', () =\u003e {\n  // Do something after the client has registered with the server API.\n  // Note: it might not have received updated feature toggles yet.\n});\n\nunleash.once('changed', () =\u003e {\n  console.log(`Demo is enabled: ${unleash.isEnabled('Demo')}`);\n});\n\nunleash.on('count', (name, enabled) =\u003e console.log(`isEnabled(${name})`));\n```\n\n## Bootstrap\n\n\u003e Available from v3.11.x\n\nThe Node.js SDK supports a bootstrap parameter, allowing you to load the initial feature toggle\nconfiguration from somewhere else than the Unleash API. The bootstrap `data` can be provided as an\nargument directly to the SDK, as a `filePath` to load, or as a `url` to fetch the content from.\nBootstrap is a convenient way to increase resilience, where the SDK can still load fresh toggle\nconfiguration from the bootstrap location, even if the Unleash API should be unavailable at startup.\n\n### 1. Bootstrap with data passed as an argument\n\n```js\nconst client = initialize({\n  appName: 'my-application',\n  url: 'https://app.unleash-hosted2.com/demo/api/',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n  bootstrap: {\n    data: [\n      {\n        enabled: false,\n        name: 'BootstrapDemo',\n        description: '',\n        project: 'default',\n        stale: false,\n        type: 'release',\n        variants: [],\n        strategies: [{ name: 'default' }],\n      },\n    ],\n  },\n});\n```\n\n### 2. Bootstrap via a URL\n\n```js\nconst client = initialize({\n  appName: 'my-application',\n  url: 'https://app.unleash-hosted.com/demo/api/',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n  bootstrap: {\n    url: 'http://localhost:3000/proxy/client/features',\n    urlHeaders: {\n      Authorization: 'bootstrap',\n    },\n  },\n});\n```\n\n### 3. Bootstrap from a file\n\n```js\nconst client = initialize({\n  appName: 'my-application',\n  url: 'https://app.unleash-hosted.com/demo/api/',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n  bootstrap: {\n    filePath: '/tmp/some-bootstrap.json',\n  },\n});\n```\n\n## Toggle definitions\n\nSometimes you might be interested in the raw feature toggle definitions.\n\n```js\nimport {\n  initialize,\n  getFeatureToggleDefinition,\n  getFeatureToggleDefinitions,\n} from 'unleash-client';\n\ninitialize({\n  url: 'http://unleash.herokuapp.com/api/',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n  appName: 'my-app-name',\n  instanceId: 'my-unique-instance-id',\n});\n\nconst featureToggleX = getFeatureToggleDefinition('app.ToggleX');\nconst featureToggles = getFeatureToggleDefinitions();\n```\n\n## Custom store provider\n\n(Available from v3.11.x)\n\nBy default, this SDK will use a store provider that writes a backup of the feature toggle\nconfiguration to a **file on disk**. This happens every time it receives updated configuration from\nthe Unleash API. You can swap out the store provider with either the provided in-memory store\nprovider or a custom store provider implemented by you.\n\n### 1. Use `InMemStorageProvider`\n\n```js\nimport { initialize, InMemStorageProvider } from 'unleash-client';\n\nconst client = initialize({\n  appName: 'my-application',\n  url: 'http://localhost:3000/api/',\n  customHeaders: { Authorization: '\u003cYOUR_API_TOKEN\u003e' },\n  storageProvider: new InMemStorageProvider(),\n});\n```\n\n### 2. Custom store provider backed by Redis\n\n```js\nimport { initialize, InMemStorageProvider } from 'unleash-client';\n\nimport { createClient } from 'redis';\n\nclass CustomRedisStore {\n  async set(key, data) {\n    const client = createClient();\n    await client.connect();\n    await client.set(key, JSON.stringify(data));\n  }\n  async get(key) {\n    const client = createClient();\n    await client.connect();\n    const data = await client.get(key);\n    return JSON.parse(data);\n  }\n}\n\nconst client = initialize({\n  appName: 'my-application',\n  url: 'http://localhost:3000/api/',\n  customHeaders: {\n    Authorization: 'my-key',\n  },\n  storageProvider: new CustomRedisStore(),\n});\n```\n\n## Custom repository\n\nYou can manage the underlying data layer yourself if you want to. This enables you to use Unleash\noffline, from a browser environment, or by implement your own caching layer. See\n[example](examples/custom_repository.js).\n\nUnleash depends on a `ready` event of the repository you pass in. Be sure that you emit the event\n**after** you've initialized Unleash.\n\n## Usage with HTTP and HTTPS proxies\n\nYou can connect to the Unleash API through the corporate proxy by setting one of the environment\nvariables: `HTTP_PROXY` or `HTTPS_PROXY`.\n\n## Design philosophy\n\nThis feature flag SDK is designed according to our design philosophy. You can\n[read more about that here](https://docs.getunleash.io/topics/feature-flags/feature-flag-best-practices).\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUnleash%2Funleash-node-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FUnleash%2Funleash-node-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUnleash%2Funleash-node-sdk/lists"}