Developers

Evaluate locally.Verify everything.

Native SDKs for JavaScript/TypeScript, Python and Go, with OpenFeature providers, and any other language through OpenFeature (OFREP). A CLI and GitHub integrations for CI and pull requests. The code that runs in your app is Apache-2.0, and every bundle it receives is signed.

Read the quickstart SDK on GitHubnpm i @nanoflags/sdk

@nanoflags/sdk 0.4.0nanoflags 0.1.0 (Python)Go SDK v0.1.0Apache-2.0

Languages

Native in three languages. Open to every other.

The native SDKs download the signed configuration once, verify it and evaluate in-process, with live updates. Every other language reads the same flags through an OpenFeature OFREP provider.

Native SDKs

JavaScript / TypeScript
@nanoflags/sdk 0.4.0Node, browsers, edge runtimes, React
npm i @nanoflags/sdk
JavaScript SDK docs npm (opens in a new tab)
Python
nanoflags 0.1.0Python 3.9+asyncio
pip install nanoflags
Python SDK docs PyPI (opens in a new tab)
Go
Go module v0.1.0Go 1.22+
go get github.com/motazalmaroai/nanoflags-sdk/go
Go SDK docs pkg.go.dev (opens in a new tab)

All three run the same evaluation engine, tested against 21,998 shared evaluation cases generated from the reference engine: same inputs, same results in JavaScript, Python and Go.

Any language via OpenFeature (OFREP)

The NanoFlags edge implements the OpenFeature Remote Evaluation Protocol. Official OFREP providers exist for these languages and more, so teams using them can call NanoFlags today:

OFREP guide

Java
.NET
PHP
Ruby
Swift
Kotlin
and others

Quickstart

Three steps to your first flag.

Create a free project, copy an SDK key from Settings → Keys, then:

Install the SDK
ESM and CommonJS builds with TypeScript types. React is an optional peer dependency.
terminal
npm install @nanoflags/sdk

Create one client

One client per process. It loads the bundle, opens the live connection and verifies signatures in the background.

flags.ts

import { createClient } from "@nanoflags/sdk";

export const flags = createClient({
  sdkKey: process.env.NANOFLAGS_SDK_KEY!,   // nf_srv_… (server) or nf_pub_… (browser)
  baseUrl: "https://edge.nanoflags.io",
  service: "checkout-api",
});

await flags.ready(); // never rejects

Read a flag

Accessors are local and synchronous. They never perform I/O and never throw: without a bundle they return your fallback.

checkout.ts

const on = flags.boolean("checkout-v2", false, { key: user.id, region: "EU" });
// Local and synchronous. Returns false only if no configuration has ever loaded.

Full quickstart

SDK

The same engine in every runtime.

Each SDK runs the evaluation engine the edge, the CLI and CI run, so a result in your test is the result in production. Pick a runtime:

Signatures verified by default on the official edge, with the production keys embedded (JavaScript 0.4.0+, Python and Go from 0.1.0).
Live updates over one WebSocket; server-sent events and polling as fallbacks.
Waiting for readiness never throws; status tells you ready, stale or not-ready.
Browser keys receive only client-exposed flags.

JavaScript SDK Python SDK Go SDK React guide

server.ts

import { createClient } from "@nanoflags/sdk";

const flags = createClient({
  sdkKey: process.env.NANOFLAGS_SDK_KEY!,
  baseUrl: "https://edge.nanoflags.io",
  service: "checkout-api",
});
await flags.ready();

const result = flags.evaluate("checkout-v2", false, { key: user.id, region: "EU" });
// { value, reason: "rule_match", ruleIndex: 1, inRollout: true, bucket: 37.12, revision: 184 }

flags.on("update", (u) => console.log("r" + u.revision, u.transport, u.latencyMs));

import { createClient } from "@nanoflags/sdk";

const flags = createClient({
  sdkKey: "nf_pub_…",            // browser key: only client-exposed flags
  baseUrl: "https://edge.nanoflags.io",
});
await flags.ready();

if (flags.boolean("new-onboarding", false, { key: visitorId })) showNewOnboarding();

import { createClient } from "@nanoflags/sdk";
import { NanoFlagsProvider, useFlag, useFlagsStatus } from "@nanoflags/sdk/react";

const client = createClient({
  sdkKey: "nf_pub_…",
  baseUrl: "https://edge.nanoflags.io",
  bootstrap: window.__FLAGS__, // the bundle the server rendered with, so the first render matches
});

export function App({ user }) {
  return (
    <NanoFlagsProvider client={client} context={{ key: user.id }}>
      <Checkout />
    </NanoFlagsProvider>
  );
}

function Checkout() {
  const v2 = useFlag("checkout-v2", false);
  const { status } = useFlagsStatus(); // "not-ready" | "ready" | "stale"
  return v2 ? <NewCheckout /> : <OldCheckout />;
}

import os
from nanoflags import NanoFlags   # pip install nanoflags

flags = NanoFlags(os.environ["NANOFLAGS_SDK_KEY"], service="checkout-api")
flags.wait_until_ready(timeout=5)  # never raises

on = flags.bool_variation("checkout-v2", False, {"key": user.id, "region": "EU"})
# Evaluated locally. Falls back to False only if no config has ever loaded.

flags.on_change(lambda e: print(f"r{e.revision}", e.transport, e.latency_ms))

import nanoflags "github.com/motazalmaroai/nanoflags-sdk/go"

client, err := nanoflags.New(os.Getenv("NANOFLAGS_SDK_KEY"), nanoflags.WithService("checkout-api"))
if err != nil {
	log.Fatal(err)
}
defer client.Close()
_ = client.WaitForReady(ctx) // nil once a configuration is in use

on := client.BoolVariation("checkout-v2", nanoflags.Context{"key": user.ID, "region": "EU"}, false)
// Evaluated locally. Falls back to false only if no config has ever loaded.

OpenFeature

Keep your call sites standard.

The OpenFeature providers wrap a NanoFlags client: for the JavaScript server and web SDKs, for Python and for Go. Evaluation stays local inside the provider; NanoFlags keeps doing the loading and the live updates. Your flag calls use the OpenFeature standard API.

Install

npm i @nanoflags/openfeature-provider

OpenFeature guide Other languages: OFREP

flags.ts

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

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

const on = await OpenFeature.getClient().getBooleanValue("checkout-v2", false, { targetingKey: user.id });

import { OpenFeature } from "@openfeature/web-sdk";
import { createClient } from "@nanoflags/sdk";
import { NanoFlagsWebProvider } from "@nanoflags/openfeature-provider/web";

const nanoflags = createClient({ sdkKey: "nf_pub_…", baseUrl: "https://edge.nanoflags.io" });
await OpenFeature.setContext({ targetingKey: user.id, plan: user.plan });
await OpenFeature.setProviderAndWait(new NanoFlagsWebProvider({ client: nanoflags }));

from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from nanoflags import NanoFlags
from nanoflags.openfeature import NanoFlagsProvider   # pip install "nanoflags[openfeature]"

api.set_provider_and_wait(NanoFlagsProvider(NanoFlags(sdk_key), close_client=True))
on = api.get_client().get_boolean_value("checkout-v2", False, EvaluationContext(targeting_key=user.id))

import (
	"github.com/open-feature/go-sdk/openfeature"
	nanoflags "github.com/motazalmaroai/nanoflags-sdk/go"
	"github.com/motazalmaroai/nanoflags-sdk/go/ofprovider"
)

client, _ := nanoflags.New(os.Getenv("NANOFLAGS_SDK_KEY"))
_ = openfeature.SetProviderAndWait(ofprovider.New(client, ofprovider.WithCloseClient()))
on, _ := openfeature.NewDefaultClient().BooleanValue(ctx, "checkout-v2", false,
	openfeature.NewEvaluationContext(user.ID, nil))

CLI

Flags from the terminal and from CI.

@nanoflags/cli works with a CI key (export, scenarios, code references) or an admin key (all of that, plus creating flags and publishing). SDK keys are refused.

nanoflags flags create <key> --type boolean
Create a flag with a type, default, name and description.
nanoflags eval <flag> --context '{…}'
Evaluate a context against the draft or the published revision, with the reason and the trace.
nanoflags scenarios run --source draft
Run scenario checks for a commit; exit code 1 when one fails.
nanoflags refs scan . --repo owner/name
Find flag references in your code and upload them.
nanoflags publish --expected-revision <n>
Publish the draft, following the environment's policy.
nanoflags export --out project.json
Export the whole project as JSON.

Pass the key in NANOFLAGS_KEY, not as an argument: arguments are visible in process lists and shell history.

Install

npm i -g @nanoflags/cli

terminal

export NANOFLAGS_KEY=nf_adm_…          # admin key: create flags, publish

nanoflags flags create new-checkout --description "New checkout flow"
nanoflags flags create search-limit --type number --default 25

nanoflags eval checkout-v2 --context '{"key":"user_42","region":"EU"}'
# checkout-v2 = true
# reason: rule_match · rule r2 (#2) · inside rollout (bucket 37.12)
# source: draft of production

CLI reference

GitHub

Flag checks where the code is reviewed.

Two ways to bring NanoFlags into pull requests: an Action you add to a workflow, and an App you install once.

GitHub Action

Runs your scenario checks for a commit and fails the job when one fails; optionally uploads code references. Use a CI key: it can run scenarios but can't publish, and the action refuses admin keys.

.github/workflows/flags.yml

name: Flags
on:
  pull_request:          # NOT pull_request_target
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  scenarios:
    runs-on: ubuntu-latest
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - uses: motazalmaroai/nanoflags-sdk/integrations/github-action@main   # pin to a commit SHA
        with:
          key: ${{ secrets.NANOFLAGS_CI_KEY }}
          source: draft

CI guide

GitHub App

A pull request comment with the state of every flag the change references, edited in place.
A “NanoFlags scenarios” check run against the draft or published revision you choose.
Code references from your default branch, and cleanup hints for flags nobody reads.

GitHub App guide

Verify it yourself

Signed bundles, public keys.

Every published revision is signed with Ed25519 before it is distributed. The public keys are served without authentication, so you can check a bundle with nothing but curl and your own code.

Fetch the public keys
A JSON list of JWKs, each with a kid and a status. During a rotation the old key is listed as retiring.
Read the signature headers
The edge sends the signature, the key id and the environment id with every signed bundle.
Verify the canonical string
Ed25519 over the string below, where the last line is the SHA-256 of the bundle text exactly as sent. The SDK does exactly this.

Signature format

terminal

# 1. Public signing keys (no authentication)
curl -s https://edge.nanoflags.io/v1/keys
# {"keys":[{"kty":"OKP","crv":"Ed25519","x":"…","kid":"k1","alg":"EdDSA","use":"sig","status":"active"}]}

# 2. A signed bundle and its signature headers
curl -s -D headers.txt -o bundle.json \
  -H "Authorization: Bearer $NANOFLAGS_SDK_KEY" https://edge.nanoflags.io/v1/bundle
grep -i '^x-nanoflags-' headers.txt
# X-NanoFlags-Signed: true
# X-NanoFlags-Key-Id: k1
# X-NanoFlags-Signature: …
# X-NanoFlags-Environment-Id: …

# 3. Ed25519 signature over this canonical string
nanoflags-bundle-v1
<environment id>
<revision>
<checksum>
<sha256 hex of bundle.json, byte for byte>

Resources

Everything else, in the open.

Apache-2.0: the evaluation engine, the SDKs, the OpenFeature providers, the CLI and the GitHub Action. The dashboard and the edge are hosted services.

Start with one flag.

Explore is free: one project, three environments, every SDK and the CLI.

Start free Read the quickstart

checkout-v2	on · 50% EU	25% EU
new-pricing-page	off	off