# @kameleoon/nodejs-sdk

> Kameleoon NodeJS SDK

Latest version **5.29.0** (published 2026-10-14) · ISC license · 0 weekly downloads

## Install

```sh
npm install @kameleoon/nodejs-sdk
pnpm add @kameleoon/nodejs-sdk
yarn add @kameleoon/nodejs-sdk
bun add @kameleoon/nodejs-sdk
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.29.0 |
| Published | 2026-10-14 |
| First published | 2023-03-21 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 2.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | mmunhurrun, vinyutochkin, kameleoon-sdk |
| Keywords | kameleoon, nodejs, sdk, nodejs sdk |

## Links

- npm: https://www.npmjs.com/package/@kameleoon/nodejs-sdk
- Homepage: https://developers.kameleoon.com/nodejs-sdk.html
- npm.io page: https://npm.io/package/@kameleoon/nodejs-sdk

## Dependencies (1)

- [@kameleoon/javascript-sdk-core](https://npm.io/package/@kameleoon/javascript-sdk-core.md) 5.28.0

## Recent versions

- 5.29.0 (latest) — 2026-10-14
- 5.28.0 — 2026-09-15
- 5.27.1 — 2026-09-11
- 5.27.0 — 2026-08-28
- 5.26.2 — 2026-07-10
- 5.26.1 — 2026-05-20
- 5.26.0 — 2026-05-14
- 5.25.0 — 2026-05-07
- 5.24.0 — 2026-05-05
- 5.23.0 — 2026-04-23
- 5.22.0 — 2026-03-23
- 5.21.0 — 2026-03-19
- 5.20.0 — 2026-03-04
- 5.19.0 — 2026-02-13
- 5.18.2 — 2026-02-09
- … 93 more at https://npm.io/package/@kameleoon/nodejs-sdk/versions

## README

# Kameleoon NodeJS SDK

## Introduction

Kameleoon NodeJS SDK is used to work with Kameleoon Feature Flags and Experiments using native NodeJS api.
Integration of this SDK on server is easy, and its footprint is low.

This page describes the most basic `KameleoonClient` configuration, for more in-depth review of all the methods and configuration options follow [Official Kameleoon Documentation](https://developers.kameleoon.com/nodejs-sdk.html)

## Contents

- [Installation](#installation)
- [Configuration](#configuration)
- [Usage Example](#usage-example)
- [External Dependencies](#external-dependencies)

## Installation

- **npm** - `npm install @kameleoon/nodejs-sdk`
- **yarn** - `yarn add @kameleoon/nodejs-sdk`
- **pnpm** - `pnpm add @kameleoon/nodejs-sdk`
- **bun** - `bun install @kameleoon/nodejs-sdk`

## Configuration

1. Obtain your site code and credentials from [Kameleoon Platform](https://app.kameleoon.com/)
2. Instantiate a client providing [external dependencies](#external-dependencies).

```ts
import { KameleoonClient } from '@kameleoon/nodejs-sdk';
import { KameleoonVisitorCodeManager } from '@kameleoon/nodejs-visitor-code-manager';
import { KameleoonEventSource } from '@kameleoon/nodejs-event-source';
import { KameleoonRequester } from '@kameleoon/nodejs-requester';

const client = new KameleoonClient({
  siteCode: 'my_site_code',
  credentials: {
    clientId: 'my_id',
    clientSecret: 'my_secret',
  },
  externals: {
    visitorCodeManager: new KameleoonVisitorCodeManager(),
    eventSource: new KameleoonEventSource(),
    requester: new KameleoonRequester(),
  },
});
```

## Usage Example

```ts
// -- Wait for the client initialization
await client.initialize();

// -- Generate or obtain a visitor code
const visitorCode = KameleoonClient.getVisitorCode({
  request: req, // `NodeJS/NextJS/Deno` request object
  response: res, // `NodeJS/NextJS/Deno` response object
});

// -- Add targeting data
const customDataIndex = 0;
client.addData(visitorCode, new CustomData(customDataIndex, 'my_data'));

// -- Check if the feature flag is active
const isActive = client.isFeatureFlagActive(visitorCode, 'my_feature_key');
```

## External Dependencies

NodeJS SDK utilizes certain external dependencies, which are required to be able to use specific API when working in different contexts.

There are several possible external dependencies used by Kameleoon NodeJS SDK, some of them have default Kameleoon implementations in form of external npm packages, while other are SDK built-ins, but can still be re-implemented by the developers using an SDK.

Here is the list of such dependencies:

- `visitorCodeManager`_(mandatory)_ is responsible for managing the visitor code and cookies, it has several default Kameleoon implementations:
  - `@kameleoon/nodejs-visitor-code-manager`
  - `@kameleoon/nextjs-visitor-code-manager`
  - `@kameleoon/deno-visitor-code-manager`
- `eventSource`_(mandatory)_ is responsible for Real Time Updates(Streaming) for SDK, it has one default Kameleoon implementation:
  - `@kameleoon/nodejs-event-source` (suitable for NodeJS/Deno/NextJS)
- `requester`_(mandatory)_ is responsible for sending all SDK request, it has one default Kameleoon implementation:
  - `@kameleoon/nodejs-requester`
- `storage`_(optional)_ is responsible for storing all SDK related data, it has a built-in implementation in the SDK.

Following is the example implementation for each dependency.

### visitorCodeManager

```ts
import {
  IExternalVisitorCodeManager,
  GetDataParametersType,
  KameleoonUtils,
} from '@kameleoon/nodejs-sdk';

class MyVisitorCodeManager implements IExternalVisitorCodeManager {
  // - Get visitor code from `request` cookie
  public getData({ request, key }: GetDataParametersType): string | null {
    const cookieString = request.headers.cookie;

    if (!cookieString) {
      return null;
    }

    return KameleoonUtils.getCookieValue(cookieString, key);
  }

  // - Set visitor code to `response` cookie
  public setData({
    visitorCode,
    response,
    domain,
    maxAge,
    key,
    path,
  }: SetDataParametersType): void {
    let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`;

    if (domain) {
      resultCookie += `; Domain=${domain}`;
    }

    response.setHeader('Set-Cookie', resultCookie);
  }
}
```

### eventSource

```ts
import { IExternalEventSource } from '@kameleoon/nodejs-sdk';

class MyEventSource implements IExternalEventSource {
  private eventSource?: EventSource;

  public open({
    eventTypes,
    onEvent,
    url,
  }: EventSourceOpenParametersType): void {
    // - Use any suitable EventSource implementation here
    const eventSource = new EventSource(url);

    this.eventSource = eventSource;
    eventTypes.forEach((eventType) => {
      eventSource.addEventListener(eventType, onEvent);
    });
  }

  public close(): void {
    if (this.eventSource) {
      this.eventSource.close();
    }
  }

  // - Lets the SDK restore the connection or fall back to polling. Without it
  //   the SDK keeps polling enabled alongside streaming; it will become
  //   required in the next major version
  public onError(callback: (error: Event) => void): void {
    if (this.eventSource) {
      this.eventSource.onerror = callback;
    }
  }
}
```

### storage

```ts
import { IExternalStorage } from '@kameleoon/nodejs-sdk';

const storage = new Map();

class MyStorage<T> implements IExternalStorage<T> {
  public read(key: string): T {
    // - Utilize the storage implementation of your choice
    const data = storage.get(key);

    // - Optionally handle errors
    if (!data) {
      throw new Error("Couldn't read data from myStorage");
    }

    return data;
  }

  public write(key: string, data: T): void {
    storage.set(key, data);
  }
}
```

### requester

```ts
import {
  RequestType,
  IExternalRequester,
  SendRequestParametersType,
} from '@kameleoon/nodejs-sdk';

class Requester implements IExternalRequester {
  public async sendRequest({
    url,
    parameters,
  }: SendRequestParametersType<RequestType>) {
    // - Using built-in `fetch` API (for Node version 18+)
    return await fetch(url, parameters);
  }
}
```

---
_Source: https://npm.io/package/@kameleoon/nodejs-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._