Flags SDK Updates & Release Notes

Minor Changes

#403 4705ac6 Thanks @dferber90! - Simplify usage and improve evaluation of the Edge Config adapter

When multiple flags share the same Edge Config adapter, the SDK now evaluates them in a single batched call instead of one by one.

You can also now pass the adapter by reference instead of calling it:

import { edgeConfigAdapter } from "@flags-sdk/edge-config";
// before (still supported)
flag({ key: "example", adapter: edgeConfigAdapter() });
// now also works
flag({ key: "example", adapter: edgeConfigAdapter });

Minor Changes

#390 7b5ea9a Thanks @luismeyer! - Add OIDC authentication support for Vercel Flags clients and generated flag definitions.

@vercel/flags-core can now create clients without an SDK key and authenticate with a Vercel OIDC token, while still supporting SDK keys and connection strings. Bundled definitions can be looked up by SDK key hash or OIDC project ID.

@vercel/prepare-flags-definitions now collects both SDK keys and VERCEL_OIDC_TOKEN, fetches definitions for each auth entry, deduplicates identical definitions across SDK keys and OIDC project IDs, and writes generated maps keyed by SDK key hash or project ID.

@flags-sdk/vercel now supports provider data lookup for Vercel flag origins that do not include an SDK key, allowing OIDC-backed clients to resolve project metadata.

Minor Changes

#385 201f9d5 Thanks @dferber90! - Add bulkEvaluate method to FlagsClient for resolving multiple flags against shared entities in a single call.

const results = await client.bulkEvaluate(
[
{ key: "a", defaultValue: false },
{ key: "b", defaultValue: "off" },
],
entities
);
results.a; // EvaluationResult<boolean>
results.b; // EvaluationResult<string>

Avoids the per-flag overhead of separate evaluate() calls — the datafile is read once, entities are resolved once, and all flags share the same environment/segments lookup. Each entry in the returned record is a full EvaluationResult with value, reason, outcomeType, and metrics.

#371 bd4d01a Thanks @vincent-derks! - Add jitter to ingest retries and the batch-flush window.

The usage tracker now uses AWS-style "Full Jitter" exponential backoff between retry attempts (replacing the previous deterministic 100/200ms schedule) and randomizes the 5s batch-flush window by ±20% to desynchronize concurrent processes. When all retry attempts are exhausted the SDK now logs a structured warning so consumers can alert on dropped batches.

#390 7b5ea9a Thanks @luismeyer! - Add OIDC authentication support for Vercel Flags clients and generated flag definitions.

@vercel/flags-core can now create clients without an SDK key and authenticate with a Vercel OIDC token, while still supporting SDK keys and connection strings. Bundled definitions can be looked up by SDK key hash or OIDC project ID.

@vercel/prepare-flags-definitions now collects both SDK keys and VERCEL_OIDC_TOKEN, fetches definitions for each auth entry, deduplicates identical definitions across SDK keys and OIDC project IDs, and writes generated maps keyed by SDK key hash or project ID.

@flags-sdk/vercel now supports provider data lookup for Vercel flag origins that do not include an SDK key, allowing OIDC-backed clients to resolve project metadata.

Patch Changes

#382 4d90e91 Thanks @dferber90! - Speed up flag evaluation on the hot path.

handleOutcome no longer recomputes scaledWeights on every split-outcome evaluation; the per-outcome scaled weights are cached on first call.

matchConditions no longer recompiles RegExp on every REGEX / NOT_REGEX condition; the compiled regex is cached on first call.

Controller.read() and getDatafile() no longer re-destructure and re-spread the in-memory datafile on every call; the result is cached and rebuilt only when stream/poll replaces the underlying data.

In micro-benchmarks the pure evaluate() path is ~22% faster for split outcomes and ~32% faster for regex conditions. The full client.evaluate() path is 14–22% faster across all scenarios.

Minor Changes

• #385 201f9d5 Thanks @dferber90! - Reduces overhead when evaluating multiple flags via evaluate() or precompute() by using new bulk evaluation capabilities of @vercel/flags-core.
• #390 7b5ea9a Thanks @luismeyer! - Add OIDC authentication support for Vercel Flags clients and generated flag definitions.

@vercel/flags-core can now create clients without an SDK key and authenticate with a Vercel OIDC token, while still supporting SDK keys and connection strings. Bundled definitions can be looked up by SDK key hash or OIDC project ID.

@vercel/prepare-flags-definitions now collects both SDK keys and VERCEL_OIDC_TOKEN, fetches definitions for each auth entry, deduplicates identical definitions across SDK keys and OIDC project IDs, and writes generated maps keyed by SDK key hash or project ID.

@flags-sdk/vercel now supports provider data lookup for Vercel flag origins that do not include an SDK key, allowing OIDC-backed clients to resolve project metadata.

Patch Changes

Updated dependencies [201f9d5, 4d90e91, bd4d01a, 7b5ea9a]:
@vercel/[email protected]

Minor Changes

• #385 201f9d5 Thanks @dferber90! - When applications call evaluate() or precompute() function from flags/next it now defers bulk evaluation to the underlying adapters in case those support it, or otherwise falls back to evaluating each flag individually.

This speeds up evaluation for applications that need to evaluate multiple flags at once, as the runtime needs to handle fewer promises and more work is reused. In testing we have seen a 20x improvement when called with 100 flags.

import { evaluate } from "flags/next";
import { flagA, flagB } from "../flags";

// pass a list of flags
const [valueA, valueB] = await evaluate([flagA, flagB]);

// pass an object
const { a, b } = await evaluate({ a: flagA, b: flagB });

Adapters can opt into bulk evaluation by implementing a bulkDecide method and setting a stable adapterId. When both are present, flag evaluation groups flags that share the same adapterId and identify source and invokes bulkDecide once per group instead of calling decide per flag. Flags without a bulk-capable adapter still resolve through the normal per-flag path inside evaluate() and still benefit from now reusing the shared per-request headers, cookies, and overrides reads.

Tracing reflects this grouping. evaluate() (and therefore precompute()) now emits an evaluate span carrying a flagCount attribute. Within it, bulk-evaluated flags no longer emit an individual per-flag run span; instead each adapter group emits a single batch span (carrying the adapterId, the keys evaluated in the batch, and cachedCount/overrideCount/decidedCount attributes summarizing how the batch resolved) so per-flag instrumentation overhead is not reintroduced. Flags that fall back to the per-flag path continue to emit their own flag span as before.

Patch Changes

• c08f3e5: Improve performance by caching next/headers imports. Previously every flag evaluation in Next.js App Router would run await import("next/headers"). The imported module is cached by the runtime, but we would still go through the event loop unnecessarily. Now we cache the resolved module in a local variable so only the first call awaits the dynamic import; subsequent calls skip the microtask entirely.

• c08f3e5: Reduce microtask queue overhead in flag evaluation by replacing the async IIFE around decide() with a direct call and Promise.resolve().