Flags uses the same model, the same user object and the same bucket hashing, so a migration is an import, an SDK swap and a check.
Plan for an afternoon per product: import (minutes), run both SDKs side by side and compare, then switch your apps over one environment at a time. Nothing in ConfigCat changes until you turn it off.
1
Concept map
ConfigCat concepts in Flags
ConfigCat
Flags
Organization
Workspace
Product
Project
Config
Config
Environment
Environment (one SDK key per config and environment, as in ConfigCat)
Feature flag / setting
Setting (boolean, string, integer, number, json)
Targeting rule, percentage options
Rule, percentages (per rule or for everyone else)
Segment
Segment (per project)
Prerequisite flag
Prerequisite condition
Sensitive (hashed) comparators
Confidential comparators (*_hashed)
Audit log
History, with diff, notes and Restore this version
Flag keys are kept as they are. Flags keys start with a letter and contain letters, digits, _, . and -, up to 128 characters; a ConfigCat key outside that is listed in the dry run as unsupported. Environment and config keys become lowercase slugs of their names (Production → production), and segment names become segment keys.
Buckets are sticky across the move. Every imported flag's seed is its ConfigCat key, and Flags hashes like ConfigCat does, so a user in the 10% in ConfigCat is in the same 10% in Flags. Renaming the flag later does not change that.
Hashed values are re-hashed, not reused. ConfigCat's hashes use its own per-config salt, which Flags cannot reuse. The importer reads the clear text of sensitive comparators through ConfigCat's Management API and hashes it again under your project's salt. Where ConfigCat returns only hashes, the dry run says so and you re-enter those values after the import.
Not supported in v1, and reported by the dry run: regular-expression and case-insensitive comparators (Flags compares case-sensitively). Predefined variations import as plain values, with their names listed.
3
Import in the console
In ConfigCat, create Public Management API credentials (My account › Public API credentials). Flags uses them for this one request and never stores, logs or caches them; delete them in ConfigCat when you are done.
In the console open Flags › Import from ConfigCat (you need flags.project.manage and flags.create; owners and admins have both). Enter the credentials, then the ConfigCat product id (in ConfigCat: the product's Product settings) and, optionally, a name for the new project.
Dry run: you see what maps, what is imported in a different form and what is unsupported, with counts. Nothing is written.
Import. If something is unsupported you can import without it (it is listed in the change note) or fix it in ConfigCat and run the dry run again. Production-named environments are imported protected.
Step 1: the ConfigCat Public Management API credentials, sent with this import only.Step 2: the ConfigCat product id (Product settings in ConfigCat) and the new project’s name. Next comes the dry run, which writes nothing.
The same import from code, dry run first:
import.ts
import { Flags } from "@productcraft/flags";
const flags = new Flags(); // PRODUCTCRAFT_API_KEY + PRODUCTCRAFT_WORKSPACE_ID
// ConfigCat Public Management API credentials: used for this request
// only, never stored, logged or echoed.
const credentials = {
username: process.env.CONFIGCAT_API_USERNAME!,
password: process.env.CONFIGCAT_API_PASSWORD!,
};
const dry = await flags.imports.create({
source: "configcat",
credentials,
configcat_product_id: "08d8a0b0-0000-4c1f-8a1c-1a2b3c4d5e6f",
dry_run: true,
});
console.log(dry.report.counts, dry.report.unsupported, dry.report.warnings);
if (dry.report.unsupported.length === 0) {
const real = await flags.imports.create({
source: "configcat",
credentials,
configcat_product_id: "08d8a0b0-0000-4c1f-8a1c-1a2b3c4d5e6f",
dry_run: false,
});
console.log("project", real.project?.id);
}
4
Swap the SDK
ConfigCat SDK calls in Flags
ConfigCat (JavaScript)
@productcraft/flags
configcat.getClient(key, PollingMode.AutoPoll, …)
new FlagsClient({ sdkKey, polling: { mode: "auto" } })
Before you switch, prove both SDKs give every user the same answer.
configcat-dual-run.mjs in the SDK repository loads both SDKs side by side, evaluates every flag for a set of synthetic users and, if you give it one, a file of your real user objects (it runs on your machine; nothing is sent anywhere), and prints every difference.
