Configuration

ToggldClient.create(options) in the Promise API and layer(options) in the Effect API take the same options.

import { ToggldClient } from "@toggld/node";

const flags = await ToggldClient.create({
  sdkKey: process.env.TOGGLD_SDK_KEY!,
  endpoint: process.env.TOGGLD_API_URL!,
  mode: "local",
  timeoutMs: 5000,
  defaultContext: { service: "checkout-api" },
  sync: { transport: "poll", pollIntervalMs: 30_000, readyTimeoutMs: 5000 },
  telemetry: { flushIntervalMs: 30_000 },
});

Client optionsCopy Anchor Link

Sync optionsCopy Anchor Link

See Local evaluation for how these settings affect update timing, and Flag files for the file option.

Environment variablesCopy Anchor Link

The client does not read TOGGLD_SDK_KEY or TOGGLD_API_URL by itself. Only the pull CLI does. The examples in these docs use those names by convention and pass the values to create.

TelemetryCopy Anchor Link

In network-synchronized local mode, the SDK counts evaluations and sends the counts to POST /v1/telemetry. The counts appear in Analytics.

• The SDK groups counts by flag, variant, reason, and UTC minute.
• It sends a batch every flushIntervalMs (default 30 seconds) and on close(). Evaluations never wait for these requests.
• It never sends user identities, evaluation context, values, or metadata.
• It counts engine results for known flags, including engine errors. It does not count unknown flags, calls before the client is ready, or type mismatches in typed getters.
• evaluateAll counts each flag once.

Remote mode sends no SDK telemetry, because the API counts remote evaluations. File-backed clients send no telemetry.

Send counts nowCopy Anchor Link

await flags.getBooleanValue("new-checkout", false, { targetingKey: "user-123" });
await flags.flushTelemetry();

flushTelemetry() never fails your code. If a send fails, the batch stays queued, and the SDK retries it with the same batch ID so that the API does not count it twice.

Turn telemetry offCopy Anchor Link

const flags = await ToggldClient.create({ sdkKey, endpoint, mode: "local", telemetry: false });

LimitsCopy Anchor Link

• The SDK holds up to 10,000 groups that it has not sent yet, plus up to 10,000 groups that wait for a retry. When the active buffer is full, the SDK drops new groups.
• Each request carries up to 1,000 groups.
• Each count stops at 1,000,000,000.
• Flag keys and variant names longer than 256 characters produce no telemetry.
• A process crash loses the counts in its buffer, so counts are approximate.