Skip to content
NanoFlags
Start free

Tooling

Moving to NanoFlags

A checklist for moving existing flags without surprises: switch the evaluation behind OpenFeature, import the definitions into drafts, compare real contexts side by side, then cut over one environment at a time. Nothing is published until you publish it.

1. Prepare

  • List the flags you use. Flags that always serve the same value are a good moment to remove from code instead of moving (nanoflags cleanup proposes the edit).
  • Agree on a short change freeze in the old system for the flags being moved, so the export stays current until the cut-over.
  • Create the NanoFlags project and its environments (development, staging, production by default), an SDK key per environment and a Management API token with flags:write (and segments:write).
  • Note which context attributes your applications pass today. NanoFlags contexts are flat: the user's ID is key, every other attribute is a top-level field.

2. Swap the provider

If your applications evaluate flags through OpenFeature, the move in code is one line per service: register the NanoFlags provider instead of the previous one. Flag keys, default values and evaluation calls stay as they are. For languages without a NanoFlags provider, use the OFREP endpoint.

checkout-api
import { OpenFeature } from "@openfeature/server-sdk";
import { createClient } from "@nanoflags/sdk";
import { NanoFlagsProvider } from "@nanoflags/openfeature-provider/server";

// Before: OpenFeature.setProviderAndWait(new PreviousProvider(...))
const nanoflags = createClient({ sdkKey: process.env.NANOFLAGS_SDK_KEY!, baseUrl: "https://edge.nanoflags.io", service: "checkout-api" });
await OpenFeature.setProviderAndWait(new NanoFlagsProvider({ client: nanoflags }));

// Unchanged application code:
const client = OpenFeature.getClient();
const on = await client.getBooleanValue("new-checkout", false, { targetingKey: user.id, country: user.country });
  • Not on OpenFeature yet? Wrap the existing calls behind OpenFeature first, with the old provider, and ship that on its own. The switch is then a configuration change.
  • Make the provider choice a setting (environment variable), so each service and environment can switch, and switch back, without a deploy of new code.
  • OpenFeature's targetingKey is the NanoFlags key. See OpenFeature for supported semantics and reasons.

3. Import

  • Export the definitions from the old system and run a dry run: Import flags describes the formats, the environment mapping and conflict policies; gates and dynamic configs has the details for console API exports.
  • Read every warning. Unsupported features (flag dependencies, version or regular-expression conditions, multi-way splits, experiments) need a decision: rebuild them in NanoFlags, simplify the rule, or accept the difference.
  • Keys may be normalised (for example headerColor becomes header-color); update those references in code or keep a mapping in your OpenFeature hook.
  • The import writes drafts only. Run it again (with --conflict overwrite) when the source changes before the cut-over.

4. Compare

Before anything is published, check that NanoFlags would answer like the old system.

  1. The fidelity report of the dry run evaluates generated contexts with the source's semantics (where they are re-implemented) and with the drafts.
  2. nanoflags import verify does the same for your own contexts: export a few hundred representative ones (JSON Lines) and list every context whose value would differ. It compares against the drafts this export file would produce (not the drafts already stored in the project), writes nothing, and also covers flags that already exist, so you can run it before or after writing the drafts. Differences that come only from percentage bucketing are counted separately.
  3. Add scenarios for the flags that matter most (pricing, access, kill switches). They run on every publish and in CI.
sh
export NANOFLAGS_API_TOKEN=nf_api_…   # scope flags:write (+ segments:write)
nanoflags import export.json --project shop --dry-run                       # preview, warnings, fidelity
nanoflags import verify export.json --contexts samples.jsonl --project shop   # side-by-side comparison
nanoflags import export.json --project shop --env-map production=production   # write drafts
nanoflags scenarios run                                                       # your scenario checks
Percentages and experiments
Percentage rollouts keep their shares, but individual users can land on the other side because the bucketing hash differs. Finish running rollouts (0 % or 100 %) before the move where a change of assignment matters, and start running experiments again in NanoFlags rather than moving them mid-flight.

5. Cut over

  1. Publish the development drafts through a change and switch development to the NanoFlags provider. Use “Try a context” on the flags to confirm values.
  2. Repeat for staging, then production: publish the environment's drafts with its normal approvals and scenario checks, then switch the provider service by service.
  3. Keep the old system unchanged and readable for a rollback window. Switching back is the provider setting from step 2.
  4. End the change freeze: from now on, flags are changed in NanoFlags only.

6. Clean up

  • Remove the previous provider and SDK from your services once the rollback window has passed.
  • Review the importer-created segments (keys ending in -grp-…) and simplify rules where nested groups are no longer needed.
  • Mark flags as permanent or temporary and set owners, so stale flags show up in the cleanup views.
  • The import history (Flags → Import flags) and the audit log keep the record of what was imported and published.