Skip to main content

Node

TypeScript Support

⭐ Recommended: Use the Quonfig CLI to generate TypeScript definitions for type-safe access to your flags and configs:

# Step 1: pull a local copy of your workspace config files
npx @quonfig/cli pull --dir ./my-config

# Step 2: generate Node.js type definitions from local files
npx @quonfig/cli generate --dir ./my-config --targets node-ts

Set QUONFIG_DIR=./my-config to avoid repeating --dir.

Install the Latest Version​

npm install @quonfig/node

TypeScript types are included with the package.

Initialize a Client​

First, pull your workspace config and generate types:

npx @quonfig/cli pull --dir ./my-config
npx @quonfig/cli generate --dir ./my-config --targets node-ts

Then use the generated typed class:

import { Quonfig } from "@quonfig/node";
import { QuonfigTypesafeNode } from "./generated/quonfig-server";

const baseQuonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY,
enableSSE: true,
fallbackPollEnabled: true,
});

await baseQuonfig.init();

// Create the typed instance
const quonfig = new QuonfigTypesafeNode(baseQuonfig);

// Now you get full type safety and autocomplete!
const myStringConfig = quonfig.myStringConfig(); // string type inferred
const myFeatureFlag = quonfig.coolFeature(); // boolean type inferred
const configWithContext = quonfig.userSpecificSetting({
user: { key: "user-123" },
}); // Type-safe context

If Quonfig is unreachable at startup​

init() fetches config from the primary and secondary delivery hosts and retries through blips (jittered backoff from 0.5s, capped at 30s) for initTimeout (10 s by default). It resolves as soon as the first config loads. If no config has loaded by then, onInitFailure decides what happens:

onInitFailureAt the timeout
"fail" (default)init() rejects with QuonfigInitError (.reason: "timeout", "unavailable" or "unauthorized"; .cause: the last delivery error).
"wait"init() keeps blocking and retrying with no upper bound, and resolves once config loads.
"continue"init() resolves, logs an ERROR, and the client starts on your code defaults.

If every delivery host rejects the SDK key (401/403/404/410), "fail" rejects at once instead of waiting out the timeout, and "continue" resolves at once; "wait" logs an ERROR and keeps retrying. initTimeout of zero or less runs exactly one attempt, then applies onInitFailure; it does not mean "no deadline". An unknown onInitFailure value throws when you construct the client.

The client object keeps retrying in the background in every mode, including after you catch a QuonfigInitError, and heals on the first successful fetch. Until then getters return the default you pass (or follow onNoDefault), and get*Details calls return reason: "ERROR" with errorCode: "PROVIDER_NOT_READY". If you catch the error and don't keep the client, call close() on it so the retry stops.

import { Quonfig, QuonfigInitError } from "@quonfig/node";

const quonfig = new Quonfig({ sdkKey, onInitFailure: "fail", initTimeout: 10_000 });
try {
await quonfig.init();
} catch (err) {
if (err instanceof QuonfigInitError) console.error(err.reason, err.message);
throw err; // let the orchestrator restart the process
}

quonfig.isReady(); // true once config is loaded
await quonfig.waitForReady({ timeoutMs: 30_000 }); // rejects with QuonfigInitError on timeout

Under "wait" or "continue", wire your readiness probe to isReady() so the orchestrator holds traffic until config loads. For how to choose between the three, see If Quonfig Is Unreachable at Startup. In AWS Lambda, keep initTimeout well under your function timeout; see Lambdas.

Local datadir mode (no account required)​

The SDK can run entirely against a local directory of JSON config files — no SDK key, no SSE connection, no telemetry POSTs. Use this when you want Quonfig as a self-contained git-backed config store, when running tests, or when developing offline.

import { Quonfig } from "@quonfig/node";
import path from "node:path";

const quonfig = new Quonfig({
// Point the SDK at a local Quonfig workspace directory.
// (Same shape as what `qfg init` creates.)
datadir: path.join(process.cwd(), "quonfig"),
// Pick which environment overrides to apply.
environment: process.env.QUONFIG_ENVIRONMENT ?? "development",
// Nothing to stream from / poll without a server.
enableSSE: false,
fallbackPollEnabled: false,
});

await quonfig.init();

With datadir set and no sdkKey provided, the SDK skips telemetry entirely — there's no workspace to attribute it to and nowhere to POST it. If you have an sdkKey, telemetry still runs in datadir mode so dogfood deployments can self-report.

The SDK reads the directory once, at init(). To pick up edits without a restart (an editor save, a git pull, a build step), opt in to file watching:

const quonfig = new Quonfig({
datadir: path.join(process.cwd(), "quonfig"),
environment: "development",
dataDirAutoReload: true, // off by default
// dataDirAutoReloadDebounceMs: 200, // wait this long after the last change
});

Each successful reload fires onConfigUpdate. If the new files don't parse, the SDK logs the error and keeps serving the previous config. If the directory can't be watched (for example, a read-only filesystem), the SDK logs it and carries on without watching.

See the Next.js + TypeScript (Fully Local) tutorial for a complete walkthrough, or the Open Source / Fully Local how-to for the mental model.

Next.js API Routes (Singleton Pattern)​

For Next.js API routes and other serverless environments, use the singleton pattern to avoid re-initialization on every request:

// app/api/flags/route.ts (or pages/api/flags.ts)
import { Quonfig, type Contexts } from "@quonfig/node";
import { QuonfigTypesafeNode } from "../../../generated/quonfig-server";
import { NextRequest, NextResponse } from "next/server";

let baseQuonfig: Quonfig | null = null;
let quonfig: QuonfigTypesafeNode | null = null;

async function getQuonfigClient(): Promise<QuonfigTypesafeNode> {
if (!baseQuonfig || !quonfig) {
const client = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,
enableSSE: true,
fallbackPollEnabled: true,
});

try {
await client.init();
} catch (err) {
// init() failed (see "If Quonfig is unreachable at startup"). Close this
// client so its background retry stops; the next request builds a new one.
await client.close();
throw err;
}
// Only cache after successful init.
baseQuonfig = client;
quonfig = new QuonfigTypesafeNode(client);
}

return quonfig;
}

export async function GET(request: NextRequest) {
const rf = await getQuonfigClient();

// Get user context from request headers, cookies, etc.
const userId = request.headers.get("x-user-id");
const context: Contexts = {
user: { key: userId || "anonymous" },
};

// Use type-safe methods with context
const welcomeMessage = rf.welcomeMessage(context);
const isFeatureEnabled = rf.newFeature(context);

return NextResponse.json({
welcomeMessage,
isFeatureEnabled,
});
}
Singleton Pattern Benefits

This pattern prevents re-initialization on every API request, which is crucial for serverless environments where functions are frequently recycled. The client is initialized once per container lifecycle and reused across requests.

Environment Variables

Make sure to use QUONFIG_BACKEND_SDK_KEY (not NEXT_PUBLIC_) in API routes since they run server-side. Only client-side code needs the NEXT_PUBLIC_ prefix.

API URLs​

By default the SDK derives all of its hostnames from QUONFIG_DOMAIN (default quonfig.com): it fetches config from https://primary.quonfig.com, streams live updates from https://stream.primary.quonfig.com, and automatically fails over to https://secondary.quonfig.com (on separate infrastructure). Failover and hedging are on by default — see Reliability for the full model.

Override the list by passing apiUrls. Pass both a primary and a secondary URL to keep automatic failover; a single URL disables it (the SDK logs a warning at init):

const quonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,
apiUrls: [
"https://primary.quonfig.com",
"https://secondary.quonfig.com",
],
});

Feature Flags and Dynamic Config​

With generated types, you get camelCase method names and full type safety:

// Instead of string keys, use type-safe methods:
if (quonfig.newUserOnboarding()) {
// boolean type inferred
// Show new user flow
}

const maxRetries = quonfig.apiRetryCount(); // number type inferred
const welcomeMessage = quonfig.welcomeMessage(); // string type inferred

// Context is type-safe too
const userSpecificLimit = quonfig.userDailyLimit({
user: { key: "user-123", plan: "pro" },
}); // Types enforced for context structure

On default settings, a read with no default throws when there is no value, including for a missing key. Pass a default, or see onNoDefault below.

Typed getters and defaults​

Every typed getter takes (key, contexts?, default?). Pass undefined for contexts to use only the global (or bound) context.

GetterReads
getStringstring and log_level configs
getBoolbool configs
getIntint configs, and doubles that are whole numbers
getNumberint and double configs
getStringListstring_list configs
getDurationduration configs, in milliseconds
getJSONjson configs (a fresh copy on every call)
getany config, as its stored type
isEnabled(key, contexts?)bool flags; false for anything else, and never throws

Values are never coerced: a stored string "false" is not a bool and "3" is not a number. When a getter has no value (a missing key, no matching rule, another type, a malformed value, an unset ENV_VAR or a decryption failure), it returns your default. Without a default, the onNoDefault option decides:

  • "error" (the default) throws: QuonfigTypeMismatchError for a wrong type, otherwise the underlying error (for a missing key, No value found for key "...").
  • "warn" logs a warning and returns undefined.
  • "ignore" returns undefined.
const quonfig = new Quonfig({ sdkKey, onNoDefault: "warn" });

The details getters, getBoolDetails, getStringDetails, getNumberDetails, getStringListDetails and getJSONDetails, never throw. They return { value, reason, variant, flagMetadata }, plus errorCode (FLAG_NOT_FOUND, TYPE_MISMATCH, PARSE_ERROR, PROVIDER_NOT_READY or GENERAL) when reason is "ERROR". evaluateDetails(key, contexts?) returns any config's value in its stored form (a duration as its ISO 8601 text, such as "PT90S") with a valueType field.

The rules are the same in every Quonfig SDK; see Typed Getters, Defaults, and Error Codes. If you are upgrading from @quonfig/node 1.x, which coerced values and returned the default less often, read the UPGRADE to 2.0 notes.

Deprecated aliases

isFeatureEnabled is a deprecated alias of isEnabled, and inContext(...) is a deprecated alias of withContext(...). Both behave identically to the new names and will be removed in a future major release. New code should use isEnabled and withContext, which match @quonfig/javascript and @quonfig/react.

Secrets​

A secret is read like any string config: quonfig.get("payments.stripe.key") (or getString) returns the decrypted string. The SDK decrypts it in your process using the encryption key, so the env var that quonfig.secrets.encryption.key is provided by (for example QUONFIG_SECRET_KEY_DEFAULT) must be set in the app's environment. If it isn't, a read that passes a default returns the default and logs one WARN per key; a read with no default throws (under the default onNoDefault: "error"). Secrets are always strings, so a JSON secret needs a parse:

const stripeKey = quonfig.getString("payments.stripe.key");
const serviceAccount = JSON.parse(quonfig.getString("gcp.service-account"));

Context​

Quonfig supports context for intelligent rule-based evaluation of get and isEnabled based on the current request/device/user/etc.

Given

import type { Contexts } from "@quonfig/node";

const context: Contexts = {
user: { key: "some-unique-identifier", country: "US" },
subscription: { key: "pro-sub", plan: "pro" },
};

With the generated typed class, context is passed directly to each method:

// Each generated method accepts context as an optional parameter
const configValue = quonfig.someConfigName(context);
const isEnabled = quonfig.someFeatureName(context);

// Or use inline context
const userSpecificValue = quonfig.welcomeMessage({
user: { key: "user-123", language: "en" },
device: { mobile: true },
}); // All type-safe!

The generated typed class wraps the base client, and every generated method takes context directly — so construct it once over baseQuonfig and pass context per call:

const typedQuonfig = new QuonfigTypesafeNode(baseQuonfig);

console.log(typedQuonfig.someConfigName(context));
console.log(typedQuonfig.someFeatureName(context));

Per-request context in Express (AsyncLocalStorage)​

In a web server you usually know who the user is in middleware, but the flag check happens several function calls deeper. Rather than passing req or a context object through every function in between, set the context once per request with Node's built-in AsyncLocalStorage and read it from anywhere in that request.

withContext(context) without a callback returns a client bound to that context. Store it for the life of the request:

// flags.ts
import { AsyncLocalStorage } from "node:async_hooks";
import type { RequestHandler } from "express";
import { Quonfig, type BoundQuonfig } from "@quonfig/node";

export const quonfig = new Quonfig({ sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY! });

const requestFlags = new AsyncLocalStorage<BoundQuonfig>();

// Register after your auth and body-parsing middleware.
export const quonfigContext: RequestHandler = (req, _res, next) => {
const bound = quonfig.withContext({
user: { key: req.user?.id, email: req.user?.email },
organization: { key: req.user?.orgId },
});
requestFlags.run(bound, next);
};

// Anywhere, at any depth: the client bound to the current request's user.
// Outside a request (startup, cron jobs) it falls back to the unbound client.
export const flags = () => requestFlags.getStore() ?? quonfig;
// app.ts
await quonfig.init();
app.use(authMiddleware);
app.use(quonfigContext);

// services/pricing.ts: no user argument needed
import { flags } from "../flags";

export async function calculateDiscount(cart: Cart) {
if (flags().isEnabled("new-discount")) {
// ...
}
}

The bound client follows the request across awaits, timers and promise chains, so concurrent requests never see each other's context. Evaluation is local and in memory, so calling flags() as often as you like costs nothing. You can still pass just-in-time context to a single call, such as flags().isEnabled("new-discount", { cart: { total: 120 } }); it merges with the request's context.

The same pattern works in Fastify, Koa, or any Node framework: call requestFlags.run(bound, ...) around the rest of the request. Register it after auth and body parsing. A few older callback-based libraries (some session stores and database pools) can lose the async context if they run inside it.

Developer overrides (qfg override)​

The qfg override CLI flips a flag for your developer machine without affecting anyone else. It does this by writing a top-priority rule on the flag keyed on the property quonfig-user.email. The SDK injects that property automatically whenever the qfg login token file is present, so the rule is dead code in production by construction (a server that never ran qfg login has no quonfig-user.email on its eval context, and the rule cannot fire).

Injection is on by default — when ~/.quonfig/tokens.json (written by qfg login) exists, the SDK reads it on init and merges { "quonfig-user": { email: <userEmail> } } into your globalContext. Customer-supplied quonfig-user keys win on collision. If the file is missing or unparseable the SDK is a no-op — init still succeeds.

To opt out (e.g. on a shared box where qfg login has run):

const quonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,
enableQuonfigUserContext: false, // opt out
});

Or set QUONFIG_DEV_CONTEXT=false in the environment. Precedence: the explicit option wins, then QUONFIG_DEV_CONTEXT, then the default (true).

Telemetry note: quonfig-user.email flows through telemetry like any other context attribute. It only appears in dev-machine telemetry because production never injects it.

Dynamic Log Levels​

Log levels in Quonfig are stored as a log_level config (e.g. log-level.my-app). Rules inside that config decide what verbosity a given logger gets — down to individual classes or modules — and changes propagate live via SSE with no restart.

Concept​

  • One log_level config per app, keyed like log-level.my-app. The value is one of TRACE, DEBUG, INFO, WARN, ERROR, FATAL.
  • Tell the SDK which config to consult by passing loggerKey at init time.
  • Every shouldLog / logger-adapter call pushes the logger's native name ("my-app.auth", "com.app.auth", whatever you use) into the evaluation context as quonfig-sdk-logging.key — verbatim, no normalization.
  • Rules match against quonfig-sdk-logging.key (or any other context property — user, environment, etc.) so one config can drive per-logger, per-user, or per-environment overrides.
  • Logger names flowing through quonfig-sdk-logging.key are auto-captured by Quonfig's example-context telemetry, so candidate logger names show up in the dashboard for rule-building.

Basic usage​

Initialize the client with loggerKey, then call shouldLog with a loggerPath:

import { Quonfig } from "@quonfig/node";

const quonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,
loggerKey: "log-level.my-app",
});

await quonfig.init();

if (quonfig.shouldLog({ loggerPath: "my-app.auth", desiredLevel: "DEBUG" })) {
console.log("auth debug line");
}

If you'd rather bypass the convenience form and point at a config directly, use the primitive shape:

quonfig.shouldLog({
configKey: "log-level.my-app",
desiredLevel: "DEBUG",
contexts: { user: { id: "user-123" } },
});

Rules​

Set levels with the qfg CLI. Each --target adds a rule that matches every logger whose name starts with that prefix:

# Default to INFO for every logger in this app
qfg log-level log-level.my-app --value=INFO

# Bump one subsystem to DEBUG
qfg log-level log-level.my-app --target=my-app.auth --value=DEBUG

# Quiet a chatty library, in one environment only
qfg log-level log-level.my-app --target=some-lib --value=ERROR --environment=production

For rules on other properties, such as turning on DEBUG for one developer by user.email, add the rule in the Quonfig app. Dynamic Log Levels walks through rule order and shows the stored JSON.

Because the evaluator sees your full context — not just quonfig-sdk-logging.* — you can combine logger rules with global or per-request context (application.environment, user.email, team.id, etc.) to crank verbosity up for a single user, a staging deploy, or one bad request, without affecting anyone else.

Winston adapter​

Install Winston as a peer dependency:

npm install winston

createWinstonFormat is a Winston format that consults quonfig.shouldLog and drops records that don't pass. Import it from the @quonfig/node/winston subpath:

import { Quonfig } from "@quonfig/node";
import { createWinstonFormat } from "@quonfig/node/winston";
import winston from "winston";

const quonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,
loggerKey: "log-level.my-app",
});
await quonfig.init();

const logger = winston.createLogger({
format: winston.format.combine(
createWinstonFormat(quonfig, "my-app.auth"),
winston.format.json()
),
transports: [new winston.transports.Console()],
});

logger.info("live-controlled"); // emits iff shouldLog says so

The second argument (loggerPath) is forwarded to quonfig.shouldLog verbatim, so rules can key on whatever identifier shape your app actually uses.

If you want a ready-to-go logger with the Quonfig gate already attached, use createWinstonLogger:

import { createWinstonLogger } from "@quonfig/node/winston";

const logger = createWinstonLogger(quonfig, "my-app.auth");
logger.debug("debug line");

Pino adapter​

Install Pino as a peer dependency:

npm install pino

createPinoHooks returns a Pino hooks object that gates every emission through Quonfig. Import it from the @quonfig/node/pino subpath:

import { Quonfig } from "@quonfig/node";
import { createPinoHooks } from "@quonfig/node/pino";
import pino from "pino";

const quonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,
loggerKey: "log-level.my-app",
});
await quonfig.init();

const logger = pino({
level: "trace", // let Pino emit everything; Quonfig decides what survives
hooks: createPinoHooks(quonfig, "my-app.auth"),
});

logger.debug("debug line");

As with Winston, the convenience constructor createPinoLogger(quonfig, loggerPath) wires the hooks for you.

Reference​

NameExampleDescription
loggerKey (constructor option)new Quonfig({ loggerKey: "log-level.my-app", ... })The log_level config consulted by the shouldLog({loggerPath}) convenience. Required for the loggerPath form.
shouldLog({loggerPath, desiredLevel, contexts?})quonfig.shouldLog({ loggerPath: "my-app.auth", desiredLevel: "DEBUG" })Convenience shape. Uses loggerKey + injects contexts["quonfig-sdk-logging"] = { key: loggerPath } so rules can target individual loggers.
shouldLog({configKey, desiredLevel, contexts?})quonfig.shouldLog({ configKey: "log-level.my-app", desiredLevel: "DEBUG" })Primitive shape. Evaluates the named config directly — no auto-injection. Use when you're building a custom adapter.
createWinstonFormat(quonfig, loggerPath, options?)winston.format.combine(createWinstonFormat(quonfig, "my-app.auth"), winston.format.json())Winston format that consults shouldLog. Import from @quonfig/node/winston.
createWinstonLogger(quonfig, loggerPath, options?)createWinstonLogger(quonfig, "my-app.auth")Ready-to-use Winston logger with the Quonfig format pre-attached. Import from @quonfig/node/winston.
createPinoHooks(quonfig, loggerPath, options?)pino({ hooks: createPinoHooks(quonfig, "my-app.auth") })Pino hooks that gate every emission through shouldLog. Import from @quonfig/node/pino.
createPinoLogger(quonfig, loggerPath, options?)createPinoLogger(quonfig, "my-app.auth")Ready-to-use Pino logger with Quonfig hooks pre-attached. Import from @quonfig/node/pino.

Mustache Templating​

Quonfig supports Mustache templating for dynamic string configurations, allowing you to create personalized messages, URLs, and other dynamic content.

Prerequisites​

Install Mustache as a peer dependency:

npm install mustache

Example Configuration​

In your Quonfig dashboard, create a string configuration with Mustache variables:

  • Configuration Key: welcome.message
  • Configuration Type: json
  • Value:
    {
    "message": "Hello {{userName}}! Welcome to {{appName}}. You have {{creditsCount}} credit(s) remaining.",
    "cta": "Buy More Credits"
    }
  • Zod Schema (optional, for validation):
    z.object({
    message: z.string(),
    cta: z.string(),
    });

Usage Examples​

The CLI generates type-safe template functions:

import {QuonfigTypesafeNode} from './generated/quonfig-server';

// Get the configured object
const welcomeMessageObject = quonfig.welcomeMessage();

// Template functions are generated automatically
// Returns: "Hello Alice! Welcome to MyApp. You have 150 credit(s) remaining."
const welcomeText = welcomeMessageObject.message({
// Type-safe parameters — every Mustache variable is typed as `string`
userName: 'Alice', // string type
appName: 'MyApp', // string type
creditsCount: '150', // string type (Mustache variables are always strings)
});

// Returns: Buy More Credits
const welcomeCta = welcomeMessageObject.cta;

Context-Aware Templating​

Combine templating with Quonfig context for personalized experiences:

const userContext = {
user: { key: "user-123", plan: "premium" },
device: { mobile: false },
};

// Template adapts based on context
const personalizedContentObject = quonfig.dynamicContent(userContext);

const personalizedMessage = personalizedContentObject.message({
name: "Alice",
planName: "Premium", // template variables are always strings
deviceType: "desktop",
});

const someOtherField = personalizedContentObject.someOtherProperty;

Escaping and limitations​

  • HTML escaping: {{variable}} HTML-escapes its output (Mustache's default), so values containing &, <, >, or " are encoded — e.g. https://example.com/?a=1&b=2 renders as https://example.com/?a=1&amp;b=2. When you need the raw, unescaped string (common for URLs), use the triple-mustache {{{variable}}} in your configuration value.
  • Variables are always strings: every {{variable}} is typed as string in the generated parameters, regardless of any Zod schema on the surrounding object. Pass '150', not 150.
  • Arrays and unions are not templated: Mustache resolution applies only to string fields on plain objects. A templated string nested inside a JSON array or union is left as a plain string — no template function is generated for it.

Reacting to Config Changes​

To run code when configuration updates arrive (via SSE or a fallback poll), pass an onConfigUpdate callback in the constructor options. You can also observe the SSE connection state with onSSEConnectionStateChange.

const quonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,

// Called after each successful config refresh
onConfigUpdate: () => {
console.log("Configuration updated; re-reading values");
updateDatabasePool(quonfig.getNumber("database.connection.pool.size"));
},

// Called when the live (SSE) connection state changes
onSSEConnectionStateChange: (state) => {
console.log("SSE connection state:", state);
},
});

await quonfig.init();

Reacting to config changes is useful for:

  • Updating application state when configs change
  • Triggering cache invalidation
  • Logging configuration changes for debugging
  • Implementing reactive configuration management

Advanced Methods​

Raw Config Access​

Access raw configuration metadata and structure:

// rawConfig and getRawMatch live on the base client, not the generated
// QuonfigTypesafeNode class. Call them on baseQuonfig (or quonfig.quonfig).
// Get raw config with full metadata (no evaluation)
const rawConfig = baseQuonfig.rawConfig("api.retry.count");
if (rawConfig) {
console.log("Config type:", rawConfig.type);
console.log("Value type:", rawConfig.valueType);
console.log("Rules:", rawConfig.default);
}

// Get the raw value that matches a given context, without unwrapping it
const rawMatch = baseQuonfig.getRawMatch("api.retry.count", {
user: { key: "user-123" },
});

Available Keys​

Get all available configuration keys:

const allKeys = quonfig.keys();
console.log(allKeys); // ["config.one", "config.two", "feature.flag", ...]

Health Accessors​

Inspect the SDK's connection state and last successful refresh:

console.log("Connection state:", quonfig.connectionState());
console.log("Last refresh:", quonfig.lastSuccessfulRefresh());

Connection Management​

Configuration stays current automatically: the SDK listens for live changes over SSE and falls back to polling when the stream is unavailable. There is no manual "update now" call — use onConfigUpdate (see Reacting to Config Changes) to run code when new config arrives.

Shutdown​

// Properly close all connections and clean up resources
await quonfig.close(); // Sends the last telemetry window (5s max), stops SSE, clears timeouts

Important: Always call quonfig.close() when shutting down your application to ensure proper cleanup of connections and prevent memory leaks.

Invalid or revoked SDK key​

If Quonfig rejects the SDK key while the client is running, @quonfig/node stops streaming, probes every 150-300 seconds until the key works again, and logs one ERROR naming the HTTP status and host (never the key). The full rule is on the Reliability page.

While the key is rejected, quonfig.connectionState() returns "disconnected", never "falling_back". Evaluation keeps serving the last installed configuration, and the client recovers by itself on the first accepted probe.

Telemetry​

Quonfig automatically collects telemetry data to help you understand how your configurations are being used. Telemetry is sent in the background; there is no public accessor for it on the client. Control collection via constructor options:

const quonfig = new Quonfig({
sdkKey: process.env.QUONFIG_BACKEND_SDK_KEY!,

// Control evaluation summaries (default: true)
collectEvaluationSummaries: true,

// Control context data collection (default: "periodic_example")
contextUploadMode: "shapes_only", // or "none" or "periodic_example"
});

Context Upload Modes:

  • "periodic_example" - Sends both context structure and example values
  • "shapes_only" - Sends only context keys and types, no values
  • "none" - Disables context collection entirely

Delivery options​

How the SDK delivers telemetry, and what it does when the endpoint is slow or down, is the same in every SDK and is explained once on the Telemetry page. The Node option names and defaults:

OptionDefault
telemetryFlushIntervalMs60000 (60s)
telemetryTimeoutMs15000 (15s)
telemetryMaxRetainedBatches5
telemetryMaxRetainedBytes2097152 (2MB)
telemetryMaxRetainedAgeMs300000 (5 min)
telemetryMaxEvaluationSummaries10000
telemetryMaxContextShapeFields10000
telemetryMaxExampleContexts10000

Invalid values (non-finite or <= 0) fall back to the default. Node's fetch has no separate connect timeout, so telemetryTimeoutMs also covers connect and TLS.

Telemetry lines go to the logger you pass. The default console logger does not print debug lines, so pass a logger to see failed POSTs.

Reference​

Option Definitions​

All options are passed to new Quonfig({...}). Every option is optional, but the client needs either an SDK key (sdkKey or QUONFIG_BACKEND_SDK_KEY) or a local datadir/datafile; otherwise the constructor throws.

Connection

NameDescriptionDefault
sdkKeyBackend SDK key (qf_sk_...). Falls back to the QUONFIG_BACKEND_SDK_KEY env var when omitted.QUONFIG_BACKEND_SDK_KEY
domainDerives the API, SSE and telemetry hostnames in one go (primary., secondary., stream. and telemetry. on this domain). Falls back to the QUONFIG_DOMAIN env var. See API URLs."quonfig.com"
apiUrlsOrdered list of API base URLs (primary + secondary; failover on by default). Wins over domain. The SSE URL is derived by prepending stream. to each hostname. A single URL disables failover.["https://primary.quonfig.com", "https://secondary.quonfig.com"]
telemetryUrlBase URL for the telemetry service. Wins over domain.https://telemetry.quonfig.com
enableSSEListen for live changes from Quonfig over SSEtrue
sseReadDeadlineMsDrop and reconnect the SSE stream if no data (including heartbeats) arrives within this many ms90000
fallbackPollEnabledPoll for changes only when the SSE stream is unavailable (replaces the deprecated enablePolling, which polled in parallel with SSE)true
fallbackPollIntervalMsHow often to poll, in ms, when the fallback poller is active (replaces the deprecated pollInterval)60000
configFetchTimeoutMsPer-URL deadline, in ms, for one config fetch, so a hung host fails over to the next one3000
configFetchHedgeDelayMsHow long, in ms, to wait for the primary before also asking the secondary in parallel2000
configFetchHedgeAbortMsHard deadline, in ms, for each hedged fetch. Keep it below initTimeout; the SDK warns at construction if it isn't.6000
initTimeoutHow long init() retries the initial config fetch, in ms, before onInitFailure applies10000
onInitFailureWhat init() does if no config loads within initTimeout: "fail", "wait" or "continue" (see startup)"fail"

Local data

NameDescriptionDefault
datadirPath to a local Quonfig workspace directory. The SDK loads config from it instead of the delivery service (see Local datadir mode).undefined
datafileA config envelope to load instead of a directory: a path to a JSON file, or the parsed object. datadir wins if both are set.undefined
environmentWhich environment's rules to apply in datadir mode. Falls back to the QUONFIG_ENVIRONMENT env var. Ignored, with a warning, when you use an SDK key without a datadir/datafile; the key picks the environment.QUONFIG_ENVIRONMENT
dataDirAutoReloadWatch datadir and re-read it when files change. A failed parse keeps serving the previous config.false
dataDirAutoReloadDebounceMsHow long, in ms, to wait after the last file change before re-reading200

Evaluation

NameDescriptionDefault
globalContextContext merged into every evaluation. A context of the same name passed to a getter or withContext replaces it.{}
onNoDefaultWhat a getter called with no default does when there is no value: "error" throws, "warn" logs and returns undefined, "ignore" returns undefined (see typed getters)"error"
enableQuonfigUserContextInject quonfig-user.email from ~/.quonfig/tokens.json (written by qfg login) into globalContext. Pairs with qfg override. Default on, gated on the token file's presence (inert in prod). Set false or QUONFIG_DEV_CONTEXT=false to opt out.null (on)

Callbacks and logging

NameDescriptionDefault
onConfigUpdateCalled after each config update (initial load, SSE push, poll or datadir reload). See Reacting to Config Changes.undefined
onSSEConnectionStateChangeCalled with "connecting", "connected", "error" or "disconnected" as the SSE connection changes. No effect when enableSSE is false.undefined
loggerReceives the SDK's own warnings and errors. Accepts a Pino, Winston or Bunyan logger, or console.console
loggerKeyThe log_level config key consulted by shouldLog({loggerPath}). Set it to enable the loggerPath convenience (see Dynamic Log Levels).undefined

Telemetry

NameDescriptionDefault
collectEvaluationSummariesSend counts of config/flag evaluation results back to Quonfig to view in the web apptrue
contextUploadModeUpload either context "shapes" (the names and data types your app uses in Quonfig contexts) or periodically send full example contexts. One of "none", "shapes_only", "periodic_example""periodic_example"
telemetry*Flush interval, timeout and retention limits. See Delivery options.