JavaScript Browser SDK

The Unleash JavaScript SDK is a lightweight client with no external dependencies (beyond browser APIs) that lets you evaluate feature flags in any JavaScript application. It is not tied to any framework, so you can use it with React, Vue, Angular, or plain JavaScript.

The SDK stores flag configuration in localStorage and synchronizes with Unleash or Unleash Edge in the background. Because flags are stored in the browser, the SDK can bootstrap itself the next time the user visits the same page.

You can use this SDK with Unleash Enterprise or Unleash Open Source.

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.

Installation

1
npm install unleash-proxy-client

Initialization

Configure the client according to your needs. The following example provides only the required options. Refer to configuration options for the full list.

Set url to the /api/frontend endpoint of your Unleash instance or your Unleash Edge instance. Set clientKey to a frontend API token.

1
import { UnleashClient } from 'unleash-proxy-client';
2
3
const unleash = new UnleashClient({
4
    url: 'https://<your-unleash-instance>/api/frontend',
5
    clientKey: '<your-frontend-token>',
6
    appName: 'my-webapp',
7
});
8
9
// Start the background polling
10
unleash.start();

Check if the SDK is ready

You should wait for the client’s ready or initialized events before you start working with it. Before it’s ready, the client might not report the correct state for your features.

1
unleash.on('ready', () => {
2
    if (unleash.isEnabled('js.demo')) {
3
        console.log('js.demo is enabled');
4
    } else {
5
        console.log('js.demo is disabled');
6
    }
7
});

The difference between the events is described in the section on available events.

Check flags

Once the client is ready, you can start checking features in your application. Use the isEnabled method to check the state of any feature you want:

1
unleash.isEnabled('js.demo');

You can use the getVariant method to get the variant of an enabled feature that has variants. If the feature is disabled or if it has no variants, then you will get back the disabled variant

1
const variant = unleash.getVariant('proxy.demo');
2
if (variant.name === 'blue') {
3
    // something with variant blue...
4
}

Unleash context

The Unleash context holds properties such as user ID, session ID, and custom fields that drive flag evaluation, including strategy targeting, constraints, and stickiness. To update and configure the Unleash context in this SDK, use the updateContext, setContextField, and removeContextField methods.

The context you set in your app will be passed along to the Unleash Edge or the Frontend API as query parameters for feature evaluation.

The updateContext method will replace the entire (mutable part) of the Unleash context with the data that you pass in.

The setContextField method only acts on the property that you choose. It does not affect any other properties of the Unleash context.

1
unleash.updateContext({ userId: '1233' });
2
3
unleash.setContextField('userId', '4141');

The removeContextField method only acts on the property that you choose. It does not affect any other properties of the Unleash context.

1
unleash.updateContext({ userId: '1233', sessionId: 'sessionNotAffected' });
2
3
unleash.removeContextField('userId');

Configuration options

The Unleash SDK takes the following options:

Events

The client is also an event emitter. This means that your code can subscribe to updates from the client. This is a neat way to update a single page app when toggle state updates.

1
unleash.on('update', () => {
2
    const myToggle = unleash.isEnabled('js.demo');
3
    //do something useful
4
});

The SDK emits the following events:

• error - emitted when an error occurs on init, or when fetch function fails, or when fetch receives a non-ok response object. The error object is sent as payload.
• initialized - emitted after the SDK has read local cached data in the storageProvider.
• ready - emitted after the SDK has successfully started and performed the initial fetch of flags via the network (Edge, or Frontend API). When bootstrapping, the client can emit this event twice: once when the bootstrapped flags are loaded, and once on first successful connection to Unleash.
• update - emitted every time Unleash returns a new feature toggle configuration. The SDK will emit this event as part of the initial fetch from the SDK.
• recovered - emitted when the SDK has recovered from an error. This event will only be emitted if the SDK has previously emitted an error.
• sent - emitted when the SDK has successfully sent metrics to Unleash.
• warn - emitted when the SDK encounters a non-fatal issue, such as invalid metric definitions.

Impact metrics

Impact metrics are lightweight, application-level time-series metrics stored and visualized directly inside Unleash. Use them to connect application data, such as request counts, error rates, or latency, to your feature flags and release plans.

The SDK automatically attaches appName, and environment labels to all impact metrics.

Initialize the SDK to start publishing impact metrics.

1
const unleash = new UnleashClient({
2
    url: 'https://<your-unleash-instance>/api/frontend',
3
    clientKey: '<your-frontend-token>',
4
    appName: 'my-webapp',
5
});
6
7
unleash.start();
8
9
unleash.impactMetrics.defineCounter(
10
  'request_count',
11
  'Total number of HTTP requests processed'
12
);
13
14
unleash.impactMetrics.incrementCounter('request_count');
15
16
unleash.impactMetrics.defineHistogram(
17
  'request_time_ms',
18
  'Time taken to process a request in milliseconds',
19
  [50, 100, 200, 500, 1000]
20
);
21
22
unleash.impactMetrics.observeHistogram('request_time_ms', 125);

Metric types

1
unleash.impactMetrics.defineCounter(
2
  'request_count',
3
  'Total number of HTTP requests processed'
4
);
5
6
unleash.impactMetrics.incrementCounter('request_count');

Impact metrics are batched and sent on the same interval as regular SDK metrics. They are ingested via the regular metrics endpoint.

Session ID

You may provide a custom session id via the “context”. If you do not provide a sessionId this SDK will create a random session id, which will also be stored in the provided storage (local storage). By always having a consistent sessionId available ensures that even “anonymous” users will get a consistent experience when feature flags are evaluated, in combination with a gradual (percentage based) rollout.

Stop the client

You can stop the Unleash client by calling the stop method. Once the client has been stopped, it will no longer check for updates or send metrics to the server.

A stopped client can be restarted.

1
unleash.stop()

Custom store

This SDK can work with React Native storage @react-native-async-storage/async-storage or react-native-shared-preferences and many more to backup feature flags locally. This is useful for bootstrapping the SDK the next time the user comes back to your application.

You can provide your own storage implementation.

Examples:

1
import SharedPreferences from 'react-native-shared-preferences';
2
import { UnleashClient } from 'unleash-proxy-client';
3
4
const unleash = new UnleashClient({
5
    url: 'https://eu.unleash-hosted.com/demo/api/frontend',
6
    clientKey: 'your-frontend-key',
7
    appName: 'my-webapp',
8
    storageProvider: {
9
      save: (name: string, data: any) => SharedPreferences.setItem(name, data),
10
      get: (name: string) => SharedPreferences.getItem(name, (val) => val)
11
    },
12
});

1
import AsyncStorage from '@react-native-async-storage/async-storage';
2
import { UnleashClient } from 'unleash-proxy-client';
3
4
const PREFIX = 'unleash:repository';
5
6
const unleash = new UnleashClient({
7
    url: 'https://eu.unleash-hosted.com/demo/api/frontend',
8
    clientKey: 'your-frontend-key',
9
    appName: 'my-webapp',
10
    storageProvider: {
11
       save: (name: string, data: any) => {
12
        const repo = JSON.stringify(data);
13
        const key = `${PREFIX}:${name}`;
14
        return AsyncStorage.setItem(key, repo);
15
      },
16
      get: (name: string) => {
17
        const key = `${PREFIX}:${name}`;
18
        const data = await AsyncStorage.getItem(key);
19
        return data ? JSON.parse(data) : undefined;
20
      }
21
    },
22
});

Node.js usage

This SDK can also be used in node.js applications (from v1.4.0). Please note that you will need to provide a valid “fetch” implementation. Only ECMAScript modules is exported from this package.

1
import fetch from 'node-fetch';
2
import { UnleashClient, InMemoryStorageProvider } from 'unleash-proxy-client';
3
4
const unleash = new UnleashClient({
5
  url: 'https://app.unleash-hosted.com/demo/api/frontend',
6
  clientKey: '<your-frontend-token>',
7
  appName: 'nodejs-proxy',
8
  storageProvider: new InMemoryStorageProvider(),
9
  fetch,
10
});
11
12
await unleash.start();
13
const isEnabled = unleash.isEnabled('proxy.demo');
14
console.log(isEnabled);

index.mjs

Developer toolbar

The Developer Toolbar wraps your Unleash client to provide runtime flag overrides during development. Install @unleash/toolbar and wrap your client:

1
import { initUnleashToolbar } from '@unleash/toolbar';
2
import { UnleashClient } from 'unleash-proxy-client';
3
import '@unleash/toolbar/toolbar.css';
4
5
const client = initUnleashToolbar(new UnleashClient({
6
  url: 'https://your-unleash.com/api/frontend',
7
  clientKey: 'your-frontend-token',
8
  appName: 'my-app'
9
}));
10
11
await client.start();
12
13
// Use the wrapped client for all flag checks
14
const isEnabled = client.isEnabled('my-feature');

The wrapped client has the same API as the original. Refer to the Developer Toolbar documentation for configuration options and framework guides.

CDN usage

1
<html>
2
<head>
3
    <script src="https://unpkg.com/unleash-proxy-client@latest/build/main.min.js" type="text/javascript"></script>
4
    <script type="text/javascript">
5
        var config = {url: 'https://app.unleash-hosted.com/demo/api/frontend', clientKey: '<your-frontend-token>', appName: 'web'};
6
        var client = new unleash.UnleashClient(config);
7
        client.updateContext({userId: '1233'})
8
9
        client.on('update', () => {
10
            console.log(client.isEnabled('proxy.demo'));
11
        });
12
        client.start();
13
    </script>
14
</head>
15
</html>

Bootstrap

You can bootstrap the SDK with your own feature flag configuration to make flags available immediately, without waiting for an API call. This is useful when you need flags in a specific state right after initialization.

Pass a bootstrap array and an optional bootstrapOverride flag when you create the client:

1
import { UnleashClient } from 'unleash-proxy-client';
2
3
const unleash = new UnleashClient({
4
  url: 'https://<your-unleash-instance>/api/frontend',
5
  clientKey: '<your-frontend-token>',
6
  appName: 'my-webapp',
7
  bootstrap: [{
8
    enabled: true,
9
    name: 'demoApp.step4',
10
    variant: {
11
      enabled: true,
12
      name: 'blue',
13
      feature_enabled: true,
14
    }
15
  }],
16
  bootstrapOverride: false
17
});

Manage your own refresh mechanism

You can opt out of the Unleash feature flag auto-refresh mechanism and metrics update by settings the refreshInterval and/or metricsInterval options to 0. In this case, it becomes your responsibility to call updateToggles and/or sendMetrics methods. This approach is useful in environments that do not support the setInterval API, such as service workers.