Flagship + Cloudflare Worker Integration Example

This project demonstrates how to integrate Flagship feature flags with Cloudflare Workers, enabling feature flagging and A/B testing at the edge.

Overview

This example shows how to:

• Initialize the Flagship SDK in a Cloudflare Worker
• Use KV storage for caching bucketing data to improve performance
• Extract visitor context from request headers
• Fetch and apply feature flags for each visitor
• Send analytics data back to Flagship

How It Works

The worker performs the following operations:

1. Retrieves Flagship credentials from environment variables
2. Loads cached bucketing data from Cloudflare KV storage
3. Initializes the Flagship SDK in edge bucketing mode
4. Creates a visitor with context data from request headers
5. Fetches feature flags for the visitor
6. Flushes analytics data back to Flagship
7. Returns flag values in a JSON response

Prerequisites

• Node.js (v18 or later)
• Yarn (v4 or later)
• A Cloudflare account
• A Flagship account with API credentials

Setup

1. Clone this repository:

git clone https://github.com/flagship-io/flagship-cloudflare-worker-example.git
cd flagship-cloudflare-worker-example

2. Install dependencies:

yarn install

3. Configure your Flagship credentials as Cloudflare Worker secrets:

wrangler secret put FLAGSHIP_ENV_ID
wrangler secret put FLAGSHIP_API_KEY

4. Create a KV namespace for caching:

wrangler kv:namespace create MY_APP_KV

5. Update the wrangler.jsonc file with your KV namespace ID

Use KV storage or direct integration for bucketing data

Bucketing data contains information about your Flagship campaigns and variations, allowing the worker to make flag decisions at the edge without calling the Flagship API for every request.

Development Approach

Option 1: KV Storage

1. Fetch bucketing data directly from the Flagship CDN:

# Replace YOUR_ENV_ID with your Flagship Environment ID
curl -s https://cdn.flagship.io/YOUR_ENV_ID/bucketing.json > bucketing-data.json

2. Upload the bucketing data to your KV namespace:

wrangler kv:key put --binding=MY_APP_KV "initialBucketing" "$(cat bucketing-data.json)"

Option 2: Direct Integration

For direct integration, you'll need to:

1. Fetch the bucketing data during your build process
2. Save it as a JSON file in your project
3. Import it directly in your worker code

# During build/deployment:
curl -s https://cdn.flagship.io/YOUR_ENV_ID/bucketing.json > src/bucketing-data.json

Then import in your code:

import bucketingData from './bucketing-data.json';
// Use this data when initializing Flagship

Production Approach

For production environments, there are two recommended approaches. Both require setting up webhooks in the Flagship platform that trigger your CI/CD pipeline when campaigns are updated. Find more details in the Flagship documentation.

Development

Start a local development server:

yarn dev

Deployment

Deploy to Cloudflare:

yarn deploy

Learn More

• Flagship Documentation
• Cloudflare Workers Documentation
• Wrangler CLI Documentation

License

This example is provided for educational purposes.