unleash-client
Advanced tools
The unleash-client npm package is a feature toggle system that allows you to control the release of features in your application. It helps you manage feature flags, enabling or disabling features without deploying new code.
Initialize Unleash Client
This code initializes the Unleash client with the necessary configuration, including the URL of the Unleash server, the application name, and the instance ID.
const { UnleashClient } = require('unleash-client');
const unleash = new UnleashClient({
url: 'http://unleash.herokuapp.com/api/',
appName: 'my-app',
instanceId: 'my-instance-id',
});
unleash.start();Check if a feature is enabled
This code checks if a specific feature toggle (in this case, 'someFeature') is enabled and logs the result.
const isEnabled = unleash.isEnabled('someFeature');
console.log(`Feature is enabled: ${isEnabled}`);Register custom strategies
This code demonstrates how to register a custom strategy with the Unleash client. Custom strategies allow you to define your own logic for enabling or disabling features.
unleash.on('ready', () => {
unleash.registerStrategy(new CustomStrategy());
});
class CustomStrategy {
constructor() {
this.name = 'custom';
}
isEnabled(parameters, context) {
// Custom logic to determine if the feature is enabled
return true;
}
}LaunchDarkly is a feature management platform that provides feature flags as a service. It offers more advanced targeting and segmentation capabilities compared to Unleash, but it is a paid service.
Flagr is an open-source feature flagging and A/B testing service. It provides a web UI for managing flags and supports various targeting rules. It is similar to Unleash in terms of being open-source but offers a different set of features and a different user interface.
fflip is a lightweight feature flagging library for Node.js. It is simpler and more lightweight compared to Unleash, making it suitable for smaller projects or those with simpler feature flagging needs.
Unleash Client SDK for Node.js. It is compatible with:
$ npm install unleash-client --save
It is recommended to initialize the Unleash client SDK as early as possible in your node.js application. The SDK will set-up a in-memory repository, and poll updates from the unleash-server at regular intervals.
const { initialize } = require('unleash-client');
const unleash = initialize({
url: 'http://unleash.herokuapp.com/api/',
appName: 'my-app-name',
instanceId: 'my-unique-instance-id',
customHeaders: {
Authorization: 'API token',
},
});
unleash.on('synchronized', () => {
// Unleash is ready to serve updated feature toggles.
// Check a feature flag
const isEnabled = unleash.isEnabled('some-toggle');
// Check the variant
const variant = unleash.getVariant('app.ToggleY');
});
Be aware that the initialize function will configure a global Unleash instance. If you call this
method multiple times the global instance will be changed. If you prefer to handle the instance
yourself you should construct your own Unleash instance.
You can also use the startUnleash function, and await for the SDK to have fully synchronized
with the unleash-api. This allows you to secure that the SDK is not operating on locally and
potential stale feature toggle configuration.
const { startUnleash } = require('unleash-client');
const unleash = await startUnleash({
appName: 'async-unleash',
url: 'http://unleash.herokuapp.com/api/',
customHeaders: {
Authorization: 'API token',
},
});
// Unleash SDK has now fresh state from the unleash-api
const isEnabled = unleash.isEnabled('Demo');
To shut down the client (turn off the polling) you can simply call the destroy-method. This is typically not required.
const { destroy } = require('unleash-client');
destroy();
The client comes with implementations for the built-in activation strategies provided by unleash.
Read more about the strategies in activation-strategy.md.
In order to use some of the common activation strategies you must provide a
unleash-context. This
client SDK allows you to send in the unleash context as part of the isEnabled call:
const unleashContext = {
userId: '123',
sessionId: 'some-session-id',
remoteAddress: '127.0.0.1',
};
unleash.isEnabled('someToggle', unleashContext);
The initialize method takes the following arguments:
customHeaders
option.rejectUnauthorized - be careful with these
options as they may compromise your application security[{type: 'simple', value: 'proxy'}].const { Strategy, initialize } = require('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()],
});
Its also possible to ship the unleash instance around yourself, instead of using on the default
require.cache to have share one instance.
const { Unleash } = require('unleash-client');
const unleash = new Unleash({
appName: 'my-app-name',
url: 'http://unleash.herokuapp.com',
customHeaders: {
Authorization: 'API token',
},
});
unleash.on('ready', console.log.bind(console, 'ready'));
// required error handling when using unleash directly
unleash.on('error', console.error);
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 toggle 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 a error |
| unchanged | - | is emitted each time the client gets new toggle state from server, but nothing has changed |
| changed | object data | is emitted each time the client gets new toggle state from server and changes has been made |
Example usage:
const { initialize } = require('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.
// NB! It might not have received updated feature toggles yet.
});
unleash.once('changed', () => {
console.log(`Demo is enabled: ${unleash.isEnabled('Demo')}`);
});
unleash.on('count', (name, enabled) => console.log(`isEnabled(${name}`)
(Available from v3.11.x)
The Node.SDK supports a bootstrap parameter, allowing you to load the initial feature toggle configuration from somewhere else than the Unleash API. The bootstrap data can be provided as an argument directly to the SDK, as a filePath to load or as a URL to fetch the content from. Bootstrap is a convenient way to increase resilience, where the SDK can still load fresh toggle configuration from the bootstrap location, even if the Unleash API should be unavailable at startup.
1. Bootstrap with data passed as an argument
const client = initialize({
appName: 'my-application',
url: 'https://app.unleash-hosted2.com/demo/api/',
customHeaders: {
Authorization: '943ca9171e2c884c545c5d82417a655fb77cec970cc3b78a8ff87f4406b495d0',
},
bootstrap: {
data: [
{
enabled: false,
name: 'BootstrapDemo',
description: '',
project: 'default',
stale: false,
type: 'release',
variants: [],
strategies: [{ name: 'default' }],
},
]
},
});
2. Bootstrap via a URL
const client = initialize({
appName: 'my-application',
url: 'https://app.unleash-hosted.com/demo/api/',
customHeaders: {
Authorization: '943ca9171e2c884c545c5d82417a655fb77cec970cc3b78a8ff87f4406b495d0',
},
bootstrap: {
url: 'http://localhost:3000/proxy/client/features',
urlHeaders: {
Authorization: 'bootstrap',
}
},
});
3. Bootstrap from a File
const client = initialize({
appName: 'my-application',
url: 'https://app.unleash-hosted.com/demo/api/',
customHeaders: {
Authorization: '943ca9171e2c884c545c5d82417a655fb77cec970cc3b78a8ff87f4406b495d0',
},
bootstrap: {
filePath: '/tmp/some-bootstrap.json',
},
});
Sometimes you might be interested in the raw feature toggle definitions.
const {
initialize,
getFeatureToggleDefinition,
getFeatureToggleDefinitions,
} = require('unleash-client');
initialize({
url: 'http://unleash.herokuapp.com/api/',
customHeaders: {
Authorization: 'API token',
},
appName: 'my-app-name',
instanceId: 'my-unique-instance-id',
});
const featureToggleX = getFeatureToggleDefinition('app.ToggleX');
const featureToggles = getFeatureToggleDefinitions();
(Available from v3.11.x)
By default this SDK will use a store provider that writes a backup of the feature toggle configuration to 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.
1. Use InMemStorageProvider
const {
initialize,
InMemStorageProvider,
} = require('unleash-client');
const client = initialize({
appName: 'my-application',
url: 'http://localhost:3000/api/',
customHeaders: {
Authorization: 'my-key',
},
storageProvider: new InMemStorageProvider(),
});
2. Custom Store Provider backed by redis
const {
initialize,
InMemStorageProvider,
} = require('unleash-client');
const { createClient } = require('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(),
});
You can manage the underlying data layer yourself if you want to. This enables you to use unleash offline, from a browser environment or implement your own caching layer. See example.
Unleash depends on a ready event of the repository you pass in. Be sure that you emit the event
after you've initialized unleash.
3.11.0
FAQs
Unleash Client for Node
The npm package unleash-client receives a total of 225,008 weekly downloads. As such, unleash-client popularity was classified as popular.
We found that unleash-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.