Unleash Proxy Client

Common errors

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

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

  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.
  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`.

Warnings

• breaking 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.
  Fix: Update calls to `unleash.setContextField()` and `unleash.removeContextField()` to `await unleash.setContextField()` or `unleash.setContextField().then(...)`.
• gotcha 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.
  Fix: Review changelogs carefully when upgrading to major versions or beta releases, especially concerning import paths and package naming.
• gotcha 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.
  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.

Install

• npm install unleash-proxy-client npm
• yarn add unleash-proxy-client yarn
• pnpm add unleash-proxy-client pnpm

Imports

• UnleashClient
  wrong:

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

  correct:

  import { UnleashClient } from '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
  wrong:

  import EVENTS from 'unleash-proxy-client'

  correct:

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

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

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

  correct:

  import type { 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.

Quickstart

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...');