unleash-client-node

This is the node client for Unleash. Read more about the Unleash project

Getting started

1. Initialize unleash-client

You should as early as possible in your node (web) app initialize the unleash-client. The unleash-client will set-up a in-memory repository, and poll updates from the unleash-server at regular intervals.

const { initialize } = require('unleash-client');
const instance = initialize({
    url: 'http://unleash.herokuapp.com/api/',
    appName: 'my-app-name',
    instanceId: 'my-unique-instance-id',
});

// optional events
instance.on('error', console.error);
instance.on('warn', console.warn);
instance.on('ready', console.log);

// metrics hooks
instance.on('registered', clientData => console.log('registered', clientData));
instance.on('sent', payload => console.log('metrics bucket/payload sent', payload));
instance.on('count', (name, enabled) => console.log(`isEnabled(${name}) returned ${enabled}`));

2. Use unleash

After you have initialized the unleash-client you can easily check if a feature toggle is enabled or not.

const { isEnabled } = require('unleash-client');
isEnabled('app.ToggleX');

3. Stop unleash

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

Built in activation strategies

The client comes with implementations for the built-in activation strategies provided by unleash.

• DefaultStrategy
• UserIdStrategy
• GradualRolloutUserIdStrategy
• GradualRolloutSessionIdStrategy
• GradualRolloutRandomStrategy
• RemoteAddressStrategy
• ApplicationHostnameStrategy

Read more about the strategies in activation-strategy.md.

Unleash context

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 context = {
    userId: '123',
    sessionId: 'some-session-id',
    remoteAddress: '127.0.0.1',
};
unleash.isEnabled('someToggle', unleashContext);

Advanced usage

The initialize method takes the following arguments:

• url - the url to fetch toggles from. (required)
• appName - the application name / codebase name
• instanceId - an unique identifier, should/could be somewhat unique
• refreshInterval - The poll-intervall to check for updates. Defaults to 15s.
• metricsInterval - How often the client should send metrics to Unleash API
• 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

Custom strategies

1. implement the custom strategy:

const { Strategy, initialize } = require('unleash-client');
class ActiveForUserWithEmailStrategy extends Strategy {
    constructor() {
        super('ActiveForUserWithEmail');
    }

    isEnabled(parameters, context) {
        return parameters.emails.indexOf(context.email) !== -1;
    }
}

2. register your custom strategy:

initialize({
    url: 'http://unleash.herokuapp.com',
    strategies: [new ActiveForUserWithEmailStrategy()],
});

Alternative usage

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 instance = new Unleash({
    appName: 'my-app-name',
    url: 'http://unleash.herokuapp.com',
});

instance.on('ready', console.log.bind(console, 'ready'));
// required error handling when using instance directly
instance.on('error', console.error);