@configcat/sdk
Advanced tools
ConfigCat is a configuration as a service that lets you manage your features and configurations without actually deploying new code.
ConfigCat SDK for JavaScript provides easy integration for your application to ConfigCat.
This repository hosts the next generation of the ConfigCat SDK for JavaScript platforms. It ships in the form of a single, unified NPM package for different JS platforms, as opposed to the one package per platform model used before.
The new SDK combines and, thus, supersedes these packages:
The new SDK maintains backward compatibility, so it can be used as a drop-in replacement for the packages listed above. In most cases you just need to replace the old package with the new and adjust the import specifiers (as shown here).
[!CAUTION] Please note that the SDK is still under development and is currently in beta phase. Use it at your own risk.
First install the NPM package:
npm i @configcat/sdk
Then import it into your application:
Frontend applications and Web Workers running in the browser:
import * as configcat from "@configcat/sdk/browser";
Node.js backend applications:
import * as configcat from "@configcat/sdk/node";
Bun backend applications:
import * as configcat from "@configcat/sdk/bun";
Deno backend applications:
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.)
Cloudflare Workers:
import * as configcat from "@configcat/sdk/cloudflare-worker";
Extensions for Chromium-based browsers (Chrome, Edge, etc.):
import * as configcat from "@configcat/sdk/chromium-extension";
Please note that these package references require your JS runtime (execution engine) or bundler to support the exports package.json field, introduced in Node.js v12.7. In the unlikely case of compatibility issues, you can fall back to
import * as configcat from "@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.
Import the package directly from a CDN server into your application:
Frontend applications and Web Workers running in the browser:
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@configcat/sdk@latest/dist/configcat.browser.umd.min.js"></script>
or
<script type="module">
import * as configcat from "https://cdn.jsdelivr.net/npm/@configcat/sdk@latest/dist/configcat.browser.esm.min.js";
</script>
Extensions for Chromium-based browsers (Chrome, Edge, etc.):
import * as configcat from "https://cdn.jsdelivr.net/npm/@configcat/sdk@latest/dist/configcat.chromium-extension.esm.min.js";
const configCatClient = configcat.getClient("#YOUR-SDK-KEY#");
You can acquire singleton client instances for your SDK keys using the
getClient("<sdkKey>")factory function. (However, please keep in mind that subsequent calls togetClient()with the same SDK Key return a shared client instance, which was set up by the first call.)
The async/await way:
const value = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false);
if (value) {
do_the_new_thing();
} else {
do_the_old_thing();
}
or the Promise way:
configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false)
.then((value) => {
if (value) {
do_the_new_thing();
} else {
do_the_old_thing();
}
});
Using this feature, you will be able to get different setting values for different users in your application by passing a User Object to getValueAsync().
Read more about Targeting here.
const userObject = new configcat.User("#USER-IDENTIFIER#");
const value = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false, userObject);
if (value) {
do_the_new_thing();
} else {
do_the_old_thing();
}
The ConfigCat SDK supports 3 different polling mechanisms to acquire the setting values from ConfigCat. After latest setting values are downloaded, they are stored in the internal cache then all requests are served from there. Read more about Polling Modes and how to use them at ConfigCat Docs.
The frontend/mobile SDKs are running in your users' browsers/devices. The SDK is downloading a config.json file from ConfigCat's CDN servers. The URL path for this config.json file contains your SDK key, so the SDK key and the content of your config.json file (feature flag keys, feature flag values, targeting rules, % rules) can be visible to your users.
This SDK key is read-only, it only allows downloading your config.json file, but nobody can make any changes with it in your ConfigCat account.
Suppose you don't want your SDK key or the content of your config.json file visible to your users. In that case, we recommend you use the SDK only in your backend applications and call a backend endpoint in your frontend/mobile application to evaluate the feature flags for a specific application customer.
Also, we recommend using sensitive targeting comparators in the targeting rules of those feature flags that are used in the frontend/mobile SDKs.
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 HTML script tag:
dist/configcat.browser.esm.min.js - for referencing the library in newer browsers via HTML script tag:
dist/configcat.chromium-extension.esm.js - for referencing the library in Chromium-based browser extensions via HTML script tag:
lib/cjs/ - for old versions of Node.js and bundlers not supporting ES modules:
Promise feature.lib/esm/ - for modern versions of Node.js, Deno and bundlers:
Promise feature.Please note that the
libbuilds target a relatively new version of the ECMAScript standard. According to node.green, this is fully compatible with the supported Node.js versions. However, if you use a bundler and want to target browsers that have no ES2017 support, please make sure that your bundler is configured to downlevel the language syntax. If you want to go all the way down to ES5, then you will need to include a polyfill for thePromisefeature as well.
This SDK should be compatible with all modern, widely used JS runtimes (execution engines) and bundlers.
The SDK is tested against the following runtimes:
The SDK should be compatible with TypeScript v4.0.2 or newer. Earlier versions may work but those are not tested, thus, not supported officially.
These tests are running on each pull request, before each deploy, and on a daily basis.
You can view a sample run here.
We strive to provide an extensive support for the various JS runtimes and build tools. If you still encounter an issue with the SDK on some platform, please open a GitHub issue or contact support.
Contributions are welcome. For more info please read the Contribution Guideline.
You might run into errors caused by the wrong version of Node.js. To make sure you are using the recommended Node.js version follow these steps.
nvm install. This will install the compatible version of Node.js.nvm use. This will use the compatible version of Node.js.ConfigCat is a feature flag and configuration management service that lets you separate releases from deployments. You can turn your features ON/OFF using ConfigCat Dashboard even after they are deployed. ConfigCat lets you target specific groups of users based on region, email or any other custom user attribute.
ConfigCat is a hosted feature flag service. Manage feature toggles across frontend, backend, mobile, desktop apps. Alternative to LaunchDarkly. Management app + feature flag SDKs.
FAQs
ConfigCat is a configuration as a service that lets you manage your features and configurations without actually deploying new code.
We found that @configcat/sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.