Registry / devops / unleash-proxy-client

unleash-proxy-client

library3.7.8jsnpmunverified

The `unleash-proxy-client` is a robust JavaScript client library tailored for integrating Unleash feature flags directly into browser-based applications. It is specifically designed to work with an Unleash Proxy or Unleash Edge instance, which acts as an intermediary to securely serve feature toggles to the frontend without exposing sensitive API keys. The current stable version is 3.7.8. The library maintains an active development pace, frequently releasing patch updates for bug fixes and minor enhancements, alongside occasional alpha/beta releases for upcoming major versions. Its core strengths include efficient context management for user and application attributes, an event-driven architecture for reacting to flag changes, and automated metrics reporting to the Unleash instance. It provides comprehensive TypeScript type definitions, significantly improving developer experience and code reliability in modern web development. This client is ideal for SPAs and server-side rendered apps where client-side feature toggle evaluation is desired.

devops

npm install unleash-proxy-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNLEASH-PROXY-CLIE

unleash-proxy-client

devopsjavascriptv3.7.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UnleashClient

✓ import { UnleashClient } from 'unleash-proxy-client'

✗ const UnleashClient = require('unleash-proxy-client')

The library primarily uses ES Modules. For CommonJS environments, you might need a transpiler or be aware of potential interoperability issues.

EVENTS

✓ import { EVENTS } from 'unleash-proxy-client'

✗ import EVENTS from 'unleash-proxy-client'

EVENTS is a named export containing constants for various client lifecycle events (e.g., 'ready', 'error', 'update').

IConfig

✓ import type { IConfig } from 'unleash-proxy-client'

✗ import { IConfig } from 'unleash-proxy-client'

For TypeScript users, import interfaces and types using `import type` for clarity and to avoid bundling type definitions at runtime.

This quickstart demonstrates how to initialize the UnleashClient, set context, listen for 'ready' and 'error' events, and check the status of a feature flag. It also shows how to react to flag updates.

import { UnleashClient, EVENTS } from 'unleash-proxy-client'; const unleash = new UnleashClient({ url: 'https://proxy.unleash.cloud/proxy', clientKey: process.env.UNLEASH_CLIENT_KEY ?? 'YOUR_CLIENT_KEY', appName: 'my-frontend-app', instanceId: 'your-instance-id', refreshInterval: 15000, // Refresh flags every 15 seconds }); unleash.on(EVENTS.READY, () => { console.log('Unleash Client is ready!'); const isNewFeatureEnabled = unleash.isEnabled('new-feature'); console.log(`'new-feature' is ${isNewFeatureEnabled ? 'enabled' : 'disabled'}`); // You can also listen for flag updates unleash.on(EVENTS.UPDATE, () => { const updatedFeatureState = unleash.isEnabled('new-feature'); console.log(`'new-feature' state updated to ${updatedFeatureState ? 'enabled' : 'disabled'}`); }); }); unleash.on(EVENTS.ERROR, (error) => { console.error('Unleash Client Error:', error); }); // Set initial context or update it later unleash.setContext({ userId: 'user123', environment: 'production', }); unleash.start(); console.log('Unleash Client started initialization...');

Debug

Known issues

breakingThe methods `setContextField` and `removeContextField` were changed to be asynchronous in version 3.7.8. Previously synchronous calls will now return a Promise and must be handled with `await` or `.then()` to ensure proper sequencing.

fix

Update calls to `unleash.setContextField()` and `unleash.removeContextField()` to `await unleash.setContextField()` or `unleash.setContextField().then(...)`.

affects: >=3.7.8

gotchaWhen migrating to newer beta versions (e.g., 3.8.0-beta.x), the underlying SDK repository references changed from `unleash-proxy-client-js` to `unleash-js-sdk`. While not directly impacting current stable usage, be aware of potential future breaking changes related to this rebranding or module paths if updating to future major versions.

fix

Review changelogs carefully when upgrading to major versions or beta releases, especially concerning import paths and package naming.

affects: >=3.8.0-beta.2

gotchaThe client requires a running Unleash Proxy or Unleash Edge instance. Connecting directly to a backend Unleash server without a proxy is generally discouraged in browser environments due to security implications and CORS restrictions.

fix

Ensure your `url` configuration points to an Unleash Proxy or Edge instance, not directly to the Unleash API server. For local development, consider using `unleash-proxy-client` with a local proxy setup.

affects: >=1.0.0

Errors

Common errors & fixes

Module 'unleash-proxy-client' has no exported member 'EVENTS'. Did you mean to use a default import?

Attempting to import `EVENTS` (or other named exports) from an incorrect path or when using a version where the export was not present or incorrectly named.

fix

Ensure you are using a recent version of `unleash-proxy-client` (e.g., >=3.8.0-beta.3 where `EVENTS` export was fixed) and using named import: `import { EVENTS } from 'unleash-proxy-client'`.

TypeError: Cannot read properties of undefined (reading 'on') when calling unleash.on()

The `UnleashClient` instance was not properly initialized or `unleash.start()` was not called before attempting to register event listeners, or attempting to call methods on an undefined or null client object.

fix

Ensure `new UnleashClient(...)` is called correctly and the client object is accessible. Call `unleash.start()` after configuration to initialize the client and begin fetching flags. Register event listeners *before* calling `start()` to catch early events like `READY`.

Upgrade

Version history

3.7.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/unleash/unleash-js-sdk ↗

packagehttps://www.npmjs.com/package/unleash-proxy-client ↗

homepagehttps://www.getunleash.io ↗