{"id":15885,"library":"unleash-proxy-client","title":"Unleash Proxy Client","description":"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.","status":"active","version":"3.7.8","language":"javascript","source_language":"en","source_url":"https://github.com/unleash/unleash-proxy-client-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install unleash-proxy-client","lang":"bash","label":"npm"},{"cmd":"yarn add unleash-proxy-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add unleash-proxy-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ES Modules. For CommonJS environments, you might need a transpiler or be aware of potential interoperability issues.","wrong":"const UnleashClient = require('unleash-proxy-client')","symbol":"UnleashClient","correct":"import { UnleashClient } from 'unleash-proxy-client'"},{"note":"EVENTS is a named export containing constants for various client lifecycle events (e.g., 'ready', 'error', 'update').","wrong":"import EVENTS from 'unleash-proxy-client'","symbol":"EVENTS","correct":"import { EVENTS } from 'unleash-proxy-client'"},{"note":"For TypeScript users, import interfaces and types using `import type` for clarity and to avoid bundling type definitions at runtime.","wrong":"import { IConfig } from 'unleash-proxy-client'","symbol":"IConfig","correct":"import type { IConfig } from 'unleash-proxy-client'"}],"quickstart":{"code":"import { UnleashClient, EVENTS } from 'unleash-proxy-client';\n\nconst unleash = new UnleashClient({\n  url: 'https://proxy.unleash.cloud/proxy',\n  clientKey: process.env.UNLEASH_CLIENT_KEY ?? 'YOUR_CLIENT_KEY',\n  appName: 'my-frontend-app',\n  instanceId: 'your-instance-id',\n  refreshInterval: 15000, // Refresh flags every 15 seconds\n});\n\nunleash.on(EVENTS.READY, () => {\n  console.log('Unleash Client is ready!');\n  const isNewFeatureEnabled = unleash.isEnabled('new-feature');\n  console.log(`'new-feature' is ${isNewFeatureEnabled ? 'enabled' : 'disabled'}`);\n\n  // You can also listen for flag updates\n  unleash.on(EVENTS.UPDATE, () => {\n    const updatedFeatureState = unleash.isEnabled('new-feature');\n    console.log(`'new-feature' state updated to ${updatedFeatureState ? 'enabled' : 'disabled'}`);\n  });\n});\n\nunleash.on(EVENTS.ERROR, (error) => {\n  console.error('Unleash Client Error:', error);\n});\n\n// Set initial context or update it later\nunleash.setContext({\n  userId: 'user123',\n  environment: 'production',\n});\n\nunleash.start();\n\nconsole.log('Unleash Client started initialization...');","lang":"typescript","description":"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."},"warnings":[{"fix":"Update calls to `unleash.setContextField()` and `unleash.removeContextField()` to `await unleash.setContextField()` or `unleash.setContextField().then(...)`.","message":"The 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.","severity":"breaking","affected_versions":">=3.7.8"},{"fix":"Review changelogs carefully when upgrading to major versions or beta releases, especially concerning import paths and package naming.","message":"When 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.","severity":"gotcha","affected_versions":">=3.8.0-beta.2"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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'`.","cause":"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.","error":"Module 'unleash-proxy-client' has no exported member 'EVENTS'. Did you mean to use a default import?"},{"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`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'on') when calling unleash.on()"}],"ecosystem":"npm"}