Cloudflare KV

Statsig offers a suite of integration tools that make usage with Cloudflare easy:

• Statsig automatically pushes project changes to Cloudflare’s KV store, providing low-latency SDK startup
• Statsig offers a Cloudflare helper that handles client initialization and event flushing, so you can focus on your business logic.

1. Configure Integration

   Navigate to Project Settings -> Integrations, in the Statsig Console, and select Cloudflare, then input:

   • Cloudflare Account ID: Can be found in Cloudflare portal on the Compute (Workers) page, under Account Details
   • KV Namespace ID: We recommend creating a new KV namespace for your Statsig integration. You can create a new namespace, and get the ID from Account Home -> Storage and Databases -> Workers KV, and copy it from the table view.
   • Cloudflare API Key: Can be found in Cloudflare portal under Account Home -> Profile -> API Tokens. You need a token with Account.Workers KV Storage Edit Permissions.

   There is also an option to filter the configs that are synced into your KV namespace by a Target App. You may wish to enable this in the future as the size of your config payload grows. When you’re getting started, leave this unchecked.

   After filling this out, click Enable.

   Within a minute, the Statsig backend should generate a config payload from your Statsig project and push it into your KV namespace. Under your KV namespace, navigate to KV Pairs - you should see an entry starting with the prefix statsig-. This is the key associated with your KV storage. Note this key down as it will be required later.

2. Add the Statsig SDK to your Worker

   Now lets hook up the SDK to read that config payload and use it for gate and experiment checks in your worker. If you’ve never created a worker before, you can follow the instructions here.

   After creating your worker, you will need to connect your KV store to your worker through a binding. Navigate to Compute (Workers) -> Select Your Worker -> Bindings -> Add binding -> KV namespace. Name your binding under Variable name. Under KV namespace, select your KV store name. For more information on connecting your worker to your KV store, you can follow the instructions here.

3. Install the Statsig SDK

   Install the Statsig serverless SDK:

   npm install @statsig/serverless-client
   

4. Import the Statsig SDK

   Import the helper

   import { handleWithStatsig } from '@statsig/serverless-client/cloudflare';
   

5. Use the SDK

   export default handleWithStatsig(handler, params)
   

   The helper method takes two arguments:

   • handler This is your Cloudflare worker fetch handler code.

   • params : ParamsObject

     Parameter	Optional	Type	Description
     kvKey	No	string	Environment variable name containing your KV pair key
     envStatsigKey	No	string	Environment variable name containing your Statsig client key
     envKvBindingName	No	string	Your KV binding name
     statsigOptions	Yes	StatsigOptions	See StatsigOptions here

   For best practice:

   • store envStatsigKey as a Cloudflare secret. You can set this in the Cloudflare dashboard under, Worker → Settings → Variables and Secrets
   • store kvKey and envKvBindingName in your wrangler.toml

   Statsig requires the three required parameters to be stored as environment variables. Either in your wrangler.toml or as Cloudflare secrets

   Example Usage

   index.js

   import { handleWithStatsig } from '@statsig/serverless-client/cloudflare';
   
   export default handleWithStatsig(
     async (request, env, ctx, client) => {
       const randomUserId = Math.floor(Math.random() * 100).toString();
       const value = client.checkGate("test_cloudflare_sync", { userID: randomUserId });
       client.logEvent('new_event', { userID: randomUserId });
       return new Response(value);
     },
     {
      kvKey: 'kv_key',
      envStatsigKey:'statsig_key', //In Cloudflare secrets, if your statsig key is stored as statsig_key=***********. Your var is "statsig_key"
      envKvBindingName:'STATSIG_KV'
     }
   )
   

That’s it! The helper automatically:

• Initializes the Statsig Client with config specs from your KV store
• Executes your handler code (Your business logic + Statsig usage)
• Flushes all events after your handler completes execution
• Cleans up resources

Advanced/manual usage

Use the advanced/manual setup if:

• You need fine-grained control over initialization timing
• You need fine-grained control over event flushing timing
• You need to customize error handling behavior

Prerequisites

1. Completed the Statsig Cloudflare KV integration setup
2. Created and bound a KV namespace to your worker

Installation

First, you’ll need to install the Statsig serverless sdk.

npm install @statsig/serverless-client

Import

Next, import the Cloudflare client.

import { StatsigCloudflareClient } from '@statsig/serverless-client/cloudflare';

Then, you need to hook it all up. This involves:

1. Creating a StatsigCloudflareClient instance.
2. Initializing the Statsig client
3. Checking a Gate
4. Logging an event
5. Flushing events to Statsig

If you’ve used a Statsig sdk in the past, these steps should be familiar. The usage will be the same, the only difference is the sdk will initialize from the KV store instead of the statsig backend.

In our example, we are checking a gate called “test_cloudflare_sync” that is set to a 50% pass rate. We create a random userID on every request, and we should see it evaluate to true 50% of the time.

1. Creating a StatsigCloudflareClient instance

const client = new StatsigCloudflareClient("<Your Statsig client key>");

The client instantiation takes two arguments:

• sdkKey : string This is your Statsig client API key. It is available from the Project Settings page in the Statsig Console. This is used to authenticate your requests.
• options : StatsigOptions See here, for more options.

For best practice:

• store sdkKey as a Cloudflare secret. You can set this in the Cloudflare dashboard under, Worker → Settings → Variables and Secrets

2. Client initialization

The following line initializes the client by loading feature gate and experiment configurations directly from your Cloudflare KV store.

const initResult = await client.initializeFromKv(env.<YOUR_KV_NAMESPACE_BINDING>, <YOUR_KV_KEY>);

The client initialization takes two arguments:

• KvBinding This is the binding you named earlier. Remember to provide this argument as env.YOUR_KV_NAMESPACE_BINDING
• KvKey : string This is the KV pair key that was generated through the Statsig integration. It can be found under Workers KV -> Your KV namespace -> KV Pairs

For best practice:

• store kvBinding and kvKey in your wrangler.toml

3. Checking a Gate

const value = client.checkGate("test_cloudflare_sync", { userID: randomUserId });

This is a gate check in code.

The checkGate method takes two arguments:

• name : string The name of the Statsig gate that you are checking.
• user : StatsigUser The Statsig user object for whom the gate is being checked. For more information on the user object, see here.

Refer to the Javascript on device evaluation sdk documentation for how to check other entities like experiments and dynamic configs.

4. Logging an event

client.logEvent('gate_check', { userID: randomUserId });

This is an event log in code.

The logEvent method takes two parameters:

• eventOrName : string | StatsigEvent This is the name and details of the event you are logging.
• user : StatsigUser The Statsig user object for whom the event is being logged.

For more information on event logging, see here.

5. Flushing Events

ctx.waitUntil(statsig.flush());

This flushes all events from the sdk to Statsig. Without this, you wont be able to get diagnostic information in the Statsig Console, nor any event data you logged.

Putting it all together

index.js

import { StatsigCloudflareClient } from '@statsig/serverless-client/cloudflare';

export default {
  async fetch(request, env, ctx) {
    try {
      const client = new StatsigCloudflareClient(env.statsig_key);
      
      const initResult = await client.initializeFromKV(env.STATSIG_KV, env.kv_key);
      
      const randomUserId = Math.floor(Math.random() * 100).toString(); //generates a random user id

      const value = client.checkGate("test_cloudflare_sync", { userID: randomUserId });

      client.logEvent('gate_check', { userID: randomUserId });

      ctx.waitUntil(client.flush());
      
      return new Response(`Value: ${value}, userID: ${randomUserId});
    } catch (error) {
      return new Response(`Error: ${error.message}`, { status: 500 });
    }
  }
};

If you want to check on the evaluations you are getting, you can go to the gate you created for this example and look at the evaluations in the Diagnostics tab.

If you want to check the events you logged, in the Statsig Console, go to Data -> Events

And there you have it - a working Cloudflare KV integration for Statsig.

Other Considerations

Polling for updates

The SDK cannot poll for updates across requests since Cloudflare does not allow for timers. To optimize for edge use cases, we do not provide an api to recognize updates to your config specs. However, when a change is made to your project definition on the Statsig console, the changes will be propagates to the KV store and will be reflected the next time you initialize the Cloudlflare client.

Flushing events

The SDK enqueues logged events and flushes them in batches. In order to ensure events are properly flushed, we recommend calling flush using context.waitUntil. This will keep the request handler alive until events are flushed without blocking the response.

context.waitUntil(client.flush());

Size Limits

Cloudflare KV has maximum size limits that may prevent Statsig from pushing configs into your KV. See here for the latest Cloudflare KV limits. If your payload continues to grow, you will need to set the option to filter the payload by a Target App in the integration settings.

Unsupported Features

Statsig ID Lists are not currently synced into Cloudflare KVs. If you rely on large (>1000) ID lists, you will not be able to check them in your Cloudflare Worker.