How to Migrate from LaunchDarkly to ConfigCat

Are you considering a switch from LaunchDarkly? Whether you're looking for more flexibility, cost-efficiency, or just a smoother developer experience, ConfigCat offers a refreshingly straightforward alternative. With a built-in import tool and transparent SDKs, moving your feature flags over is quicker than you might think. In this guide, we’ll walk you through the migration process - without breaking a sweat (or your codebase).

Why ConfigCat Is One of the Best LaunchDarkly Alternatives

When choosing the right feature flag solution for your team, there are several things to consider - from reliability to pricing to developer experience. ConfigCat checks all the boxes with a developer-first approach. Here’s why ConfigCat stands out as a top LaunchDarkly alternative:

• Over 99% uptime SLA
• Forever-free plan - full access to all features, including advanced security
• Unlimited team members in all plans
• Fast, friendly support via Slack and email, regardless of plan
• Privacy-first architecture - no user data collection

For a full breakdown, check out LaunchDarkly vs ConfigCat.

Now that you know why to switch, let’s get into how. The step-by-step guide below will show you how to migrate your feature flags from LaunchDarkly to ConfigCat using the built-in import tool.

Overview of the Migration Process

Migrating from LaunchDarkly to ConfigCat involves three main steps:

1. importing feature flags and segments,
2. replicating team roles and permissions, and
3. updating your application code to use ConfigCat’s SDKs.

Before you begin

Make sure you have:

• access to your LaunchDarkly project and environment data, and
• a ConfigCat account with Organization Admin privileges

Check platform compatibility before starting. Need help? Contact ConfigCat's support.

Step 1: Import Feature Flags from LaunchDarkly

Start by migrating your feature flags and segments using ConfigCat’s built-in import tool.

Launch the Import Tool

To start importing your feature flags:

1. Log in to your ConfigCat account.
2. Open the dropdown menu in the top-left corner of the Dashboard.
3. Navigate to Organization Overview.
4. Click Import from LaunchDarkly.

This opens a step-by-step wizard that guides you through the import process. The tool maps LaunchDarkly concepts (like flags, environments, segments) into ConfigCat’s structure automatically.

tip

You can experiment freely - imports are non-destructive. If something doesn't look right, you can delete the imported data and try again.

Step 2: Decide How to Handle LaunchDarkly’s Targeting Toggle

LaunchDarkly includes a targeting toggle on feature flags, which determines whether targeting rules are applied. ConfigCat does not have a direct equivalent, so during migration (Step 3 of the import wizard), you must choose how to handle flags where the targeting toggle is turned off. You have three options:

🔁 Option 1: Import Targeting Rules Anyway

• All targeting rules are imported, even for flags with targeting turned off in LaunchDarkly.
• The flag will behave as if targeting is on in ConfigCat, even if it was off in LaunchDarkly.

⚠️ Caution: This may change flag behavior in production, since off-variations won't be respected.

🚫 Option 2: Skip Targeting Rules

• Targeting rules are not imported if the toggle was off.
• Flags will serve only the "off" variation, just like in LaunchDarkly.

⚠️ Limitation: You lose targeting logic in these environments.

🧩 Option 3: Emulate the Toggle with a New Flag

• Adds an extra flag in ConfigCat to simulate LaunchDarkly’s targeting toggle.
• Targeting rules are imported and conditionally evaluated based on this new prerequisite flag.

✅ Best behavioral match, but adds complexity to flag logic.

Which Option Should You Pick?

• Choose Option 1 if you want all targeting logic preserved - even if it slightly changes behavior.
• Choose Option 2 if you want to match LaunchDarkly’s off-toggle behavior exactly.
• Choose Option 3 if you want the best match - but are okay with more setup.

Before proceeding:

• Review how each flag is used in different environments.
• Consider if exact behavior replication is critical or if simplifying is acceptable.

Once you've selected what and how to import in the initial steps of the wizard, the tool begins importing the selected LaunchDarkly projects one at a time. For more details on how the import process works, check out the official guide.

Final Steps After the Import

Once the import is complete, you'll see a summary showing the status of each imported LaunchDarkly project:

• Success: No major issues detected.
• Warning/Error: Manual review and adjustments are likely needed; in some cases, you may need to rerun the import.

No matter the result, it's strongly recommended to download and review the report, which includes:

• Details about detected issues during migration
• Links to original and imported items for easier troubleshooting

Step 3: Adjust the Codebase

Now that your flags and settings have been migrated, it’s time to update your application code to use ConfigCat instead of LaunchDarkly. How much work this involves depends on how you’ve been using the LaunchDarkly SDK in your app. Let’s walk through a simple example and show how to make the switch.

Adjust a Codebase that Uses LaunchDarkly SDK

Say your app currently looks something like this with LaunchDarkly:

import LaunchDarkly from '@launchdarkly/node-server-sdk';

const sdkKey = process.env.LAUNCHDARKLY_SDK_KEY ?? '#YOUR-SDK-KEY#';
const client = LaunchDarkly.init(sdkKey);

try {
  await client.waitForInitialization({ timeout: 10 });
} catch (error) {
  console.error(`SDK failed to initialize: ${error}`);
  process.exit(1);
}

const context = {
  kind: 'multi',
  user: {
    key: '#UNIQUE-USER-IDENTIFIER#',
    name: 'Alice',
    email: '[email protected]',
    country: 'UK',
  },
  organization: {
    key: '#UNIQUE-ORG-IDENTIFIER#',
    address: {
      city: 'London',
    },
  },
};

const flagValue = await client.variation(
  'isAwesomeFeatureEnabled',
  context,
  false,
);

if (flagValue) {
  console.log('Feature is enabled.');
} else {
  console.log('Feature is disabled.');
}

process.exit(0);

To migrate this to ConfigCat, follow these steps:

1. Remove LaunchDarkly and Install ConfigCat

npm uninstall @launchdarkly/node-server-sdk
npm install configcat-node

2. Import ConfigCat

import configcat from 'configcat-node';

3. Replace LaunchDarkly SDK key with ConfigCat one

🔑 Where to find your SDK key: Go to the ConfigCat Dashboard, select the config containing your imported feature flags from the sidebar, and click the “VIEW SDK KEY” button in the top right corner.

4. Set up ConfigCat client

const client = configcat.getClient(sdkKey, configcat.PollingMode.AutoPoll, {
  maxInitWaitTimeSeconds: 10,
});

note

Polling, not persistent connections: The ConfigCat client doesn’t maintain a persistent connection to the remote server. Instead, it uses polling strategies to fetch the data needed for feature flag evaluations.
For frontend apps and long-running backend services, Auto Polling is usually the best option. You can learn more about polling modes in the SDK reference.

5. Wait for Initialization (Optional)

If you're using Auto Polling mode, you can wait for the SDK to finish its initial setup before evaluating any flags - useful when your app needs to make decisions right at startup.

const clientCacheState = await client.waitForReady();
if (clientCacheState === configcat.ClientCacheState.NoFlagData) {
  process.exit(1);
}

The waitForReady() method is only available on platforms that support it (like Node.js). If you're working on a platform where it's unavailable, don’t worry - you probably don’t need it anyway.

Here's why:
Feature flag evaluation methods wait for initialization internally.
If initialization doesn’t complete within the timeout set by maxInitWaitTimeSeconds, the SDK will simply return the default value you passed in the call (e.g. false in getValueAsync('flagKey', false, user)).

You only really need to wait for initialization if:

• you're using synchronous evaluation via snapshots, and
• your app logic depends on flags right at startup.

Otherwise? You can skip this step.

Also, if you're using other polling modes, the waitForReady() logic doesn’t apply - so feel free to leave it out.

6. Rewrite LaunchDarkly contexts as ConfigCat User Objects

In ConfigCat, user and session-related context is passed using a User Object. It serves the same purpose as LaunchDarkly's context - but it's a bit simpler and more explicit.

To convert your LaunchDarkly context into a ConfigCat User Object:

1. Read the User Object documentation for your SDK.
2. Check out how context paths from LaunchDarkly are mapped to attribute names in ConfigCat.
3. See the example conversion at the end of this section.

Important Caveats to Keep in Mind

• No automatic context enrichment:
  Some LaunchDarkly SDKs automatically include extra attributes in the context object. ConfigCat does not add any attributes automatically. If your feature flags rely on those extra attributes, you’ll need to manually add them in the User Object.

• Array handling differences:
  In LaunchDarkly, all clause operators support attributes with multiple values (i.e. arrays).
  In ConfigCat, arrays are only supported with two specific comparators:

  • ARRAY CONTAINS ANY OF
  • ARRAY NOT CONTAINS ANY OF

  ❗ If you're using a different comparator with an array attribute, it won't work the same way in ConfigCat. In such cases, you may need to restructure your flag logic to align with the supported comparators.

Rewrite feature flag evaluation calls

This step is pretty straightforward — ConfigCat SDKs provide similar evaluation methods to LaunchDarkly SDKs, typically called getValue, getValueAsync, or something close.

That said, there are a few important differences you should be aware of:

• The order of parameters is different. In ConfigCat, the User Object comes last.
• Feature flag keys may be different. If a key in LaunchDarkly starts with a non-letter character or contains a dot, the import tool will change it (since those aren't valid in ConfigCat). Look for T002 translation issues in your import report to see which keys were affected.
• ConfigCat SDKs don't support automatic camel casing of flag keys.
• In statically typed languages, the default value and the flag’s actual value must match in type. (Check out this section for more info.)
• Be extra careful with number-type flags:
  • ConfigCat distinguishes between integers and decimals.
  • Use getIntValue, getDoubleValue, or the appropriate type-specific method in your language.
  • JavaScript SDKs don't have this issue, but you might run into it in C#, Java, etc.
• Some SDKs are async-only. In those cases, you can often use snapshots for synchronous evaluation - but be sure to read up on how that works, as the behavior can differ.

Here’s an adjusted code example that brings all of this together:

import configcat from 'configcat-node';

const sdkKey = process.env.CONFIGCAT_SDK_KEY ?? '#YOUR-SDK-KEY#';
const client = configcat.getClient(sdkKey, configcat.PollingMode.AutoPoll, {
  maxInitWaitTimeSeconds: 10,
});

const clientCacheState = await client.waitForReady();
if (clientCacheState === configcat.ClientCacheState.NoFlagData) {
  console.error('SDK failed to initialize.');
  process.exit(1);
}

const user = {
  identifier: '#UNIQUE-USER-IDENTIFIER#',
  email: '[email protected]',
  country: 'UK',
  custom: {
    name: 'Alice',
    'organization:key': '#UNIQUE-ORG-IDENTIFIER#',
    'organization:/address/city': 'London',
    '/kind': ['user', 'organization'],
  },
};

const flagValue = await client.getValueAsync(
  'isAwesomeFeatureEnabled',
  false,
  user,
);

if (flagValue) {
  console.log('Feature is enabled.');
} else {
  console.log('Feature is disabled.');
}

process.exit(0);

The same idea applies across other platforms too - just be aware of language-specific differences. As always, your best bet is to consult the SDK reference for your environment before implementing.

Adjust a Codebase That Uses OpenFeature

If your application uses OpenFeature as an abstraction layer for feature flagging, good news - switching to ConfigCat is typically smoother in this setup.

First, check if there’s a ConfigCat OpenFeature provider available for your platform.
If there isn’t one yet, don’t worry - you can always fall back to using the ConfigCat SDK directly (as described earlier), or reach out to ConfigCat about the missing provider.

If a provider is available, here’s what you’ll need to do to make the switch:

1. Swap the provider package.
   Uninstall the LaunchDarkly OpenFeature provider and install the ConfigCat one instead.

2. Update the initialization code.
   Look for a call to setProvider, setProviderAndWait, or something similar. Replace it with an instance of the ConfigCat OpenFeature provider.

   tip

   If setProviderAndWait is available, prefer that for proper SDK initialization.

3. Convert the evaluation context.
   You'll need to reshape your LaunchDarkly-style context object into a format that ConfigCat understands. This is very similar to how you’d convert a LaunchDarkly context to a ConfigCat User Object. Read this to learn more.

   Here’s an example:

   // LaunchDarkly-style context
   const evaluationContext = {
     kind: 'multi',
     user: {
       targetingKey: '#UNIQUE-USER-IDENTIFIER#',
       name: 'Alice',
       email: '[email protected]',
       country: 'UK',
     },
     organization: {
       targetingKey: '#UNIQUE-ORG-IDENTIFIER#',
       address: {
         city: 'London',
       },
     },
   };

   Becomes:

   // ConfigCat-compatible evaluation context
   const evaluationContext = {
     targetingKey: '#UNIQUE-USER-IDENTIFIER#',
     name: 'Alice',
     email: '[email protected]',
     country: 'UK',
     'organization:key': '#UNIQUE-ORG-IDENTIFIER#',
     'organization:/address/city': 'London',
     '/kind': ['user', 'organization'],
   };

4. Check your evaluation calls.
   Just like when switching from LaunchDarkly SDKs directly, most differences and caveats related to getValue() and attribute handling still apply here too. So give those a careful review while updating your logic.

Implementing Experiments and Analytics

There’s a key difference in how ConfigCat handles feature flag evaluations compared to LaunchDarkly.

With ConfigCat, everything happens locally in the SDK - user attributes stay in your application and never leave your system. The SDK pulls flag settings from ConfigCat’s CDN, but sends nothing back. This privacy-first approach means your users’ data is never shared with us.

The tradeoff? ConfigCat doesn’t collect data about evaluations, so it can’t offer built-in A/B testing, experiments, or analytics like LaunchDarkly does.

But no worries - you can still achieve the same goals by integrating with a third-party analytics tool. Here are a few popular options that work well with ConfigCat:

• Amplitude
• Google Analytics
• Mixpanel
• Twilio Segment

Using one of these, you can track experiment exposure and user behavior to get the insights you need - just like you did with LaunchDarkly, but with more flexibility and control.

Step 4: Migrate LaunchDarkly Teams and Permissions to ConfigCat

To wrap up your migration, you'll want to replicate your team structure and permission settings in ConfigCat.

At the moment, ConfigCat doesn't offer automated tools for this step, because there are fundamental differences in how LaunchDarkly and ConfigCat handle user management.

Understand the Differences

• LaunchDarkly supports fine-grained access control, with customizable roles defined at the organization level.
• ConfigCat keeps things simpler, using permission groups scoped per product. This makes it easier to manage, but less flexible.

Get Familiar with ConfigCat’s Permission Model

In ConfigCat, instead of global teams and roles, you create permission groups for each product. These define what users can do within that product.

Helpful resources:

• Organization & Roles
• Team Management Basics

Map Roles to Permission Groups

Now review the roles you used in LaunchDarkly and create equivalent permission groups in ConfigCat.

info

To migrate custom roles to ConfigCat, you'll need to translate the policies they define to the fixed set of permissions available in ConfigCat permission groups. This won't always be possible one-to-one.

Key points to keep in mind:

• Permission groups are scoped to a single product.
• There are no built-in roles like Reader or Writer - you'll need to create them manually.
• LaunchDarkly’s Admin and Owner roles don’t map directly. In ConfigCat, you can assign users the Organization Admin role, which applies at the org level.

You might need to simplify or adjust some permissions during this transition.

Create Permission Groups

Once you’ve mapped your roles:

• Go to the ConfigCat Dashboard.
• Select the product you're working with.
• Open the Permission Groups section in the top menu.
• Add the groups you need and assign the appropriate permissions to each.

Invite Users and Assign Roles

Now it's time to bring your users into ConfigCat:

• Invite users to ConfigCat by following these instructions.
• While inviting, select the product and the permission group the user should belong to.
• Each user can only be in one permission group per product.
• To assign users to multiple products:
  • Invite them to one product first.
  • After they sign up, go to Members & Roles, use Change roles, and assign them to other products.

Following this step-by-step process should help you rebuild your team structure in ConfigCat without too many surprises.

Final Thoughts

Migrating from LaunchDarkly to ConfigCat can seem like a big task, but it’s very manageable with the right approach. Whether you’re moving a small setup or a complex enterprise configuration, the key steps remain the same:

• Import your flags.
• Translate contexts and user attributes.
• Review and rewrite evaluation logic.
• Rebuild your teams and permissions.

By the end, you’ll have a lightweight, privacy-first solution that’s easy to work with—without the complexity or lock-in of more heavyweight platforms. Need help migrating from LaunchDarkly? Don’t hesitate to reach out to ConfigCat Support - Happy flagging!

You can stay up-to-date with ConfigCat on Facebook, X, GitHub, and LinkedIn.