Cloudflare Workers

Cloudflare Workers run in V8 isolates distributed across Cloudflare's global network. This guide wires @avsbhq/edge into a Worker so evaluation happens locally, the datafile is cached in Workers KV across cold starts, and queued events leave the isolate after the response has already gone out.

Install the edge client:

npm install @avsbhq/edge

Put the SDK key in your Worker configuration. It is environment-specific, so a staging Worker and a production Worker carry different values:

name = "my-worker"main = "src/worker.ts"compatibility_date = "2024-09-23"[vars]AVSB_SDK_KEY = "sdk_production_ttqm0eaj4vth1krcb2xn"[[kv_namespaces]]binding = "AVSB_KV"id = "<your-kv-namespace-id>"preview_id = "<your-preview-kv-namespace-id>"

If you would rather keep the value out of the repository, npx wrangler secret put AVSB_SDK_KEY works too and the code below is unchanged: both a [vars] entry and a secret arrive on env.

Bootstrap the client

import { createCloudflareHandler } from '@avsbhq/edge/cloudflare'import type { KVNamespace } from '@avsbhq/edge/cloudflare'interface Env {  AVSB_SDK_KEY: string  AVSB_KV: KVNamespace}export default {  fetch: createCloudflareHandler<Env>({    sdkKey: (env) => env.AVSB_SDK_KEY,    kv: (env) => env.AVSB_KV,    handler: async (req, client) => {      const homepage = client.getBoolFlag('new_homepage', false)      return Response.json({ enabled: homepage.isEnabled() })    },  }),}

That is the whole wiring. There is no module-scope client to memoise and no readiness check to write: the factory constructs one client per request, awaits init() before your handler runs, and calls ctx.waitUntil(client.flushEvents()) after it returns.

Reading flags

Inside the handler the client is bound to the request, so the context argument is optional:

import type { AvsbEdgeClient, EvaluationSource, Flag } from '@avsbhq/edge'interface HomepageDecision {  enabled: boolean  variationKey: string | null  source: EvaluationSource}function decideHomepage(client: AvsbEdgeClient): HomepageDecision {  const flag: Flag<boolean> = client.getBoolFlag('new_homepage', false)  return { enabled: flag.isEnabled(), variationKey: flag.variationKey, source: flag.source }}

The full set of typed getters, each returning a frozen Flag<T>:

import type { AvsbEdgeClient, EvalContext, Flag } from '@avsbhq/edge'function readEverything(client: AvsbEdgeClient, other: EvalContext): void {  const bool: Flag<boolean> = client.getBoolFlag('new_homepage', false)  const copy: Flag<string> = client.getStringFlag('cta_copy', 'Buy now')  const size: Flag<number> = client.getNumberFlag('page_size', 25)  const config: Flag<{ timeout: number }> = client.getJsonFlag('api_config', { timeout: 5000 })  // Pass a context to evaluate one call against a different identity without  // changing the one the adapter bound.  const forSomeoneElse: Flag<boolean> = client.getBoolFlag('new_homepage', false, other)  // Bulk read. Fires no exposures by default, because a bulk read is not a  // decision served to a visitor.  const all: Record<string, Flag> = client.getAllFlags()}

A typed getter checks the type the dashboard declares for the flag. On a mismatch it returns your default with source: 'not_found' and logs one line naming both types. It never coerces and never throws.

flag.source says where the value came from:

isEnabled() is true only for a real decision with a truthy value, so it is always false for default, disabled, not_found, and not_ready.

Tracking events

import type { AvsbEdgeClient } from '@avsbhq/edge'function recordConversion(client: AvsbEdgeClient, orderTotal: number): void {  client.track('signup_completed')  client.track('checkout_completed', { revenue: orderTotal })}

payload.revenue is money for this conversion and lands in the wire's revenue column. payload.value is a separate number, for a quantity like items or seats, and lands in its own value column: the two never mix. payload.properties is accepted so the call reads the same across runtimes, but it is not stored on tracked events, and the SDK warns once, naming revenue and value as the two places that are actually stored and reportable. Exposure events do carry properties, and exposures are automatic: reading a flag whose decision came from an experiment queues one.

The factory flushes for you. If you build AvsbEdgeClient by hand, call ctx.waitUntil(client.flushEvents()) at the end of every request.

Identity

You do not have to write a context. The adapter resolves the visitor from the x-avsb-visitor-id header, then the A vs B snippet's _avsb_visitor cookie, so a site running both Web Experiments and this Worker reports one visitor and both surfaces join in results. It also reads Cloudflare's own geolocation (country, region, city, continent, postal code, timezone, latitude, longitude) plus colo and asn, falling back to the cf-ipcountry header when request.cf is absent.

The client IP is deliberately never used as the bucketing key: that key is written to visitorId on every exposure row.

Supply contextFrom when you have an identity Cloudflare does not, and build on the exported helper so you keep the platform data:

import { createCloudflareHandler, cloudflareContextFrom } from '@avsbhq/edge/cloudflare'export default {  fetch: createCloudflareHandler<Env>({    sdkKey: (env) => env.AVSB_SDK_KEY,    kv: (env) => env.AVSB_KV,    contextFrom: (req) => ({      ...cloudflareContextFrom(req),      key: req.headers.get('x-user-id') ?? 'anon',      plan: req.headers.get('x-account-plan') ?? 'free',    }),    handler: async (req, client) => Response.json({ ready: client.isReady() }),  }),}

Return { kind: 'multi', ... } from contextFrom to target on more than one identity at once. There is no identify() at the edge: the context is fixed for the life of one request.

Keeping the datafile fresh

A published change reaches your Workers within the 5 minute freshness window on its own. To make it immediate, open Organization Settings, go to the Integrations tab, and register a webhook for the flag.published event. Have the receiver refresh the KV entry the adapter reads.

The webhook body carries the project, environment, and who published, not the datafile itself, so the receiver fetches the datafile and writes it under the key the KV adapter looks for:

import { fetchDatafileFromCdn } from '@avsbhq/edge'import type { KVNamespace } from '@avsbhq/edge/cloudflare'interface WebhookEnv {  AVSB_SDK_KEY: string  AVSB_KV: KVNamespace}export default {  async fetch(request: Request, env: WebhookEnv): Promise<Response> {    // Verify the delivery signature before acting on it. See the Webhooks guide.    if (request.method !== 'POST') return new Response('Method Not Allowed', { status: 405 })    const outcome = await fetchDatafileFromCdn(env.AVSB_SDK_KEY)    if (outcome.kind !== 'datafile') {      return new Response('datafile unavailable', { status: 502 })    }    await env.AVSB_KV.put(      `avsb:df:${env.AVSB_SDK_KEY}`,      JSON.stringify({ datafile: outcome.datafile, cachedAt: Date.now() }),      { expirationTtl: 86_400 },    )    return new Response('ok')  },}

fetchDatafileFromCdn returns a structured outcome (datafile, httpError, or transportError) rather than a nullable value, so a receiver can log the status and the URL it tried.

Graceful shutdown

Workers have no shutdown lifecycle: isolates are discarded silently. createCloudflareHandler already calls ctx.waitUntil(client.flushEvents()) after your handler returns, so queued exposures, tracked events, the deferred KV write, and the heartbeat all complete after the response has been delivered. There is nothing to close: an edge client lives for one request and holds no timers, sockets, or global state.

Testing

@avsbhq/test gives you a server-shaped mock whose bound client has the same read surface as the client your handler receives, so the decision logic can be tested with no network and no isolate:

import { createMockServer, flagsFromTestData, TestData } from '@avsbhq/test'import { describe, it, expect } from 'vitest'const server = createMockServer(  flagsFromTestData([    TestData.flag('new_homepage')      .booleanFlag()      .variationForUser('u_1', true)      .fallthroughVariation(false)      .build(),  ]),)describe('homepage decision', () => {  it('serves the new homepage to u_1', () => {    const visitor = server.forUser({ kind: 'user', key: 'u_1' })    expect(visitor.getBoolFlag('new_homepage', false).value).toBe(true)  })  it('serves the fallthrough to everyone else', () => {    const visitor = server.forUser({ kind: 'user', key: 'u_other' })    expect(visitor.getBoolFlag('new_homepage', false).value).toBe(false)  })  it('logs one decision per bound client', () => {    const visitor = server.forUser({ kind: 'user', key: 'u_1' })    visitor.getBoolFlag('new_homepage', false)    // Each forUser() carries its own decision log, so this count is isolated    // from the other tests in the file.    expect(visitor.getDecisionLog().entries).toHaveLength(1)  })})

To exercise the real evaluator instead of a mock, construct AvsbEdgeClient with a datafile bootstrap and logLevel: 'silent': init() then performs no network call at all.

What's next

• Edge SDK reference: the full AvsbEdgeClient API surface.
• Deno Deploy integration: the same package on Deno's edge runtime.
• Multi-context targeting: combine user, organization, and device contexts in a single evaluation.