ConfigCat SDK for JavaScript

!License

ConfigCat SDK for JavaScript provides easy integration for your application to ConfigCat.

This repository hosts the modern ConfigCat SDK for JavaScript platforms. Unlike the legacy platform-specific packages, it provides a single, unified NPM package that supports multiple JS environments.

The new SDK combines and, thus, supersedes these packages:
* configcat-common
* configcat-js
* configcat-js-ssr
* configcat-js-chromium-extension
* configcat-node

The new SDK maintains strong backward compatibility, making it a drop-in replacement for the packages listed above. In most cases you just need to replace the old package with the new one and adjust the import specifiers (as shown here).

Getting started

$3

#### _via NPM_

First install the NPM package:

``PowerShell
npm i @configcat/sdk
`

Then import it into your application:

* Frontend applications and Web Workers running in the browser:
`js
import * as configcat from "@configcat/sdk/browser";
`

* Node.js backend applications:
`js
import * as configcat from "@configcat/sdk/node";
`

* Deno backend applications:
`js
import * as configcat from "npm:@configcat/sdk/deno";
`

To make this work, you may need to enable the unstable-byonm feature or adjust your import map.

* Bun backend applications:
`js
import * as configcat from "@configcat/sdk/bun";
`

* Cloudflare Workers:
`js
import * as configcat from "@configcat/sdk/cloudflare-worker";
`

* Extensions for Chromium-based browsers (Chrome, Edge, etc.):
`js
import * as configcat from "@configcat/sdk/chromium-extension";
`

> [!NOTE]
> Please note that subpath imports require your bundler to support the exports package.json field, introduced in Node.js v12.7. In the unlikely case of bundler compatibility issues, you can fall back to importing from the main entry point @configcat/sdk. Basically, this is another entry point to the Node.js build, however, if your bundler recognizes the browser package.json field, it will also work in your browser applications seamlessly.

> [!NOTE]
> For subpath imports to work in TypeScript, you must set the moduleResolution option to node16, nodenext or bundler in your tsconfig.json. For TypeScript versions older than 4.7, where these options are not available, you need to fall back to module resolution node and importing from the main entry point @configcat/sdk.

#### _via CDN_

Import the package directly from a CDN server into your application:

* Frontend applications and Web Workers running in the browser:

`html

`

or

`html

`

* Extensions for Chromium-based browsers (Chrome, Edge, etc.):

`js

`

$3

`js
const configCatClient = configcat.getClient("#YOUR-SDK-KEY#");
`

> [!NOTE]
> You can acquire singleton client instances for your SDK Keys using the getClient("") factory function.
> (However, please keep in mind that subsequent calls to getClient() with the _same SDK Key_ return a _shared_ client instance, which was set up by the first call.)

$3

The async/await way:

`js
const value = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false);

if (value) {
do_the_new_thing();
} else {
do_the_old_thing();
}
`

or the Promise way:

`js
configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false)
.then((value) => {
if (value) {
do_the_new_thing();
} else {
do_the_old_thing();
}
});
`

Getting user-specific setting values with targeting

This feature allows you to get different setting values for different users in your application by passing a User Object to getValueAsync().

Read more about targeting here.

`js
const userObject = { identifier: "#USER-IDENTIFIER#" };
const value = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false, userObject);

if (value) {
do_the_new_thing();
} else {
do_the_old_thing();
}
`

Sample/demo apps

Currently the @configcat/sdk NPM package includes the following builds of the library:
- dist/configcat.browser.umd.min.js - for referencing the library in old browsers via a HTML