ConfigCat SDK for JavaScript SSR

Common errors

• Error 1100: Your SDK Key seems to be wrong. Please check your SDK Key. (SDK_KEY: *****YOUR-SDK-KEY-PARTIAL)

  cause The provided SDK Key for initializing the ConfigCat client is incorrect or malformed. The logged message now masks most of the key for security.
  fix Verify your SDK Key directly from the ConfigCat Dashboard. Ensure there are no typos, extra spaces, or missing characters. Copy-pasting directly is recommended. Also, check for environment variable issues if the key is loaded from there.

• TypeError: Cannot read properties of undefined (reading 'getValueAsync') or configCatClient.getValueAsync is not a function

  cause The ConfigCat client instance was not correctly initialized, or the `getValueAsync` method is being called on an undefined or improperly imported object.
  fix Ensure `getClient()` is called with a valid SDK Key and that the returned client object is assigned and used. Also, verify that the `import { getClient } from 'configcat-js-ssr';` or `import * as configcat from 'configcat-js-ssr';` statement is correct and executes successfully.

Warnings

• breaking This SDK is superseded by the new unified ConfigCat SDK for JavaScript (configcat/js-unified-sdk). It is in maintenance mode and will only receive critical security patches.
  Fix: Migrate to the new unified SDK as described in the official ConfigCat documentation: https://configcat.com/docs/sdk-reference/js-ssr/#migration-to-the-new-sdk
• breaking Official support for `configcat-js-ssr` will end on August 31, 2026. After this date, no further updates, including security patches, will be provided for this package.
  Fix: Plan and execute migration to the unified ConfigCat SDK before the end-of-life date to ensure continued security and support.
• breaking Multiple security vulnerabilities (CVE-2025-62718, CVE-2025-58754, CVE-2025-27152, XSS, etc.) have been found and fixed in the `axios` dependency across various `v8.x.x` releases. Running on older versions exposes applications to these risks.
  Fix: Always upgrade to the latest available version of `configcat-js-ssr` to ensure all transitive dependency security fixes are applied. Currently, `v8.5.3` or newer is recommended.
• gotcha The `getClient("<sdkKey>")` factory function returns a singleton instance. While convenient, this means subsequent calls with the same SDK Key will return the same client, which might lead to unexpected behavior if different configurations are intended for different parts of an application lifecycle without explicit client disposal or unique SDK keys.
  Fix: Be aware of the singleton behavior. If truly distinct client configurations are needed for the same SDK key within an application's lifecycle, ensure previous instances are explicitly disposed of, or consider using different SDK keys if appropriate. For most SSR scenarios, a single client per SDK key is desired.

Install

• npm install configcat-js-ssr npm
• yarn add configcat-js-ssr yarn
• pnpm add configcat-js-ssr pnpm

Imports

• getClient
  wrong:

  const configCatClient = require('configcat-js-ssr').getClient;

  correct:

  import { getClient } from 'configcat-js-ssr';

  The `getClient` factory function returns a singleton client instance for a given SDK key. Subsequent calls with the same key return the shared instance. ESM is the primary import method.
• User
  wrong:

  const User = require('configcat-js-ssr').User;

  correct:

  import { User } from 'configcat-js-ssr';

  Used to create a User Object for targeting specific feature flag values based on user attributes.
• * as configcat
  wrong:

  import configcat from 'configcat-js-ssr';

  correct:

  import * as configcat from 'configcat-js-ssr';

  This is a common pattern shown in the documentation to import all named exports into a namespace object.

Quickstart

This quickstart demonstrates how to initialize the ConfigCat client, fetch a feature flag value for both a generic and a specific user, and dispose of the client.

import { getClient, User } from 'configcat-js-ssr';

// Replace with your actual SDK Key from the ConfigCat Dashboard
const SDK_KEY = process.env.CONFIGCAT_SDK_KEY ?? 'YOUR_SDK_KEY';

async function initializeAndFetchFeatureFlags() {
  if (SDK_KEY === 'YOUR_SDK_KEY') {
    console.warn('Please replace YOUR_SDK_KEY with your actual ConfigCat SDK Key.');
  }

  const configCatClient = getClient(SDK_KEY);

  // Example: Get a feature flag for a generic user
  const isMyAwesomeFeatureEnabled = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false);
  console.log(`'isMyAwesomeFeatureEnabled' for generic user: ${isMyAwesomeFeatureEnabled}`);

  if (isMyAwesomeFeatureEnabled) {
    console.log('Doing the new thing!');
  } else {
    console.log('Doing the old thing.');
  }

  // Example: Get a feature flag for a specific user
  const userObject = new User('some-user-id'); // User ID can be any unique string
  userObject.setEmail('user@example.com');
  userObject.setCustom('region', 'eu');

  const valueForSpecificUser = await configCatClient.getValueAsync('isMyAwesomeFeatureEnabled', false, userObject);
  console.log(`'isMyAwesomeFeatureEnabled' for user 'some-user-id': ${valueForSpecificUser}`);

  // Don't forget to close the client when done (e.g., on app shutdown)
  // This ensures resources are released, especially important in environments like serverless functions.
  configCatClient.dispose();
}

initializeAndFetchFeatureFlags();