Choosing a runtime and mode

@toggld/js evaluates flags in four ways: three modes of ToggldClient, and the serverless client. Pick one from the runtime that your code runs on.

File mode is for local development, tests, CI, and pinned rulesets, not for following changes that you save in Toggld. See Flag files.

What each mode costsCopy Anchor Link

Toggld bills remote evaluations: each request to an OFREP evaluation endpoint counts. Definition sync (GET /sync/v1/flags and the /sync/v1/stream WebSocket) and telemetry are fair use and are not billed. Sync mode and the serverless client download definitions and evaluate in your code, so their evaluations are not billable requests. File mode makes no requests. See Plans and limits.

Definition sync still uses your rate limit: one snapshot request per poll in sync mode, and one per refresh in the serverless client. A refresh of an unchanged snapshot is a conditional request that the API answers with 304 Not Modified and no body.

How fresh each mode isCopy Anchor Link

How long after you save a flag change does your code see it? The typical times come from production benchmarks against the hosted API from one location in the western United States. Your times depend on where your code runs.

The serverless client needs a request to notice that its snapshot is old. An isolate or a process that receives no requests sees the change on its next request. To get changes sooner, lower maxAgeMs. Each refresh of an unchanged snapshot is a small 304 Not Modified response, and it is not a billable request.

• Sync mode gets most changes as a stream push within moments, and polls as a safety net. See How fast changes arrive.
• The serverless client uses a snapshot for up to maxAgeMs (default 30 seconds), then refreshes it on the next request. The API can serve a snapshot from its edge cache for up to 60 seconds after a change. So a change reaches an isolate or a process within about maxAgeMs plus 60 seconds, after it receives a request. Each isolate or process holds its own snapshot, so two of them can briefly disagree. See Freshness.
• Remote mode reads the API on every evaluation. The same edge cache can serve flag data for up to 60 seconds after a change.
• File mode follows the file, not Toggld. It adopts an edit as soon as its file watcher sees it, and re-reads the file every 30 seconds as a safety net.

RuntimesCopy Anchor Link

"Tested" means that the Toggld test suite runs the client in that runtime. "Expected" means that the runtime provides what the client needs, but Toggld does not test it yet.

Never put a secret key (ffk_) in browser code. Secret keys can read your targeting rules.

Why not sync mode everywhereCopy Anchor Link

Sync mode keeps a WebSocket, timers, and a background poll open for the life of the process.

• Cloudflare Workers and Vercel Edge run code only while a request is in progress, and the I/O of each request belongs to that request. They cannot keep a stream or a poll open. ToggldClient.create in sync mode throws a TypeError there that points to the serverless client.
• AWS Lambda, Vercel Node.js functions, and Netlify Functions freeze the process as soon as the handler returns. While the process is frozen, the stream and the poll stop, so after a freeze an evaluation can use a snapshot of any age. On Lambda, sync mode logs one warning. The serverless client checks the snapshot age in each invocation instead.
• Fastly Compute starts a fresh instance for each request and keeps no memory between requests. A serverless client would download the snapshot on every request, so remote mode costs less there.

ExamplesCopy Anchor Link

Cloudflare WorkersCopy Anchor Link

import { createServerlessClient, type ServerlessClient } from "@toggld/js/serverless";

let flags: ServerlessClient | undefined;

export default {
  async fetch(request, env, ctx): Promise<Response> {
    // One client per isolate. Create it on the first request, where `env` is available.
    flags ??= createServerlessClient({ sdkKey: env.TOGGLD_SDK_KEY, endpoint: "https://api.toggld.io" });
    const f = flags.forRequest(ctx);
    const on = await f.getBooleanValue("new-checkout", false, { targetingKey: "user-123" });
    return new Response(on ? "new checkout" : "old checkout");
  },
} satisfies ExportedHandler<Env>;

AWS LambdaCopy Anchor Link

import { createServerlessClient } from "@toggld/js/serverless";

// Module scope: the client and its snapshot survive between warm invocations.
const flags = createServerlessClient({
  sdkKey: process.env.TOGGLD_SDK_KEY!,
  endpoint: process.env.TOGGLD_API_URL!,
});

export const handler = async (event: { userId: string }) => {
  // No context: a stale snapshot is refreshed inside this invocation.
  const f = flags.forRequest();
  const on = await f.getBooleanValue("new-checkout", false, { targetingKey: event.userId });
  return { statusCode: 200, body: on ? "new checkout" : "old checkout" };
};

Node.js serverCopy Anchor Link

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

export const flags = await ToggldClient.create({
  sdkKey: process.env.TOGGLD_SDK_KEY!,
  endpoint: process.env.TOGGLD_API_URL!,
});

See Sync mode and Serverless client for the details of each.

EffectCopy Anchor Link

Both clients have an Effect API that provides the same ToggldClient service, so Effect program code is the same on every runtime. Pick the layer:

See Serverless client: Effect API.