Flagship + Fastly Compute@Edge Integration Example

This project demonstrates how to integrate Flagship feature flags with Fastly Compute@Edge, enabling feature flagging and A/B testing at the edge.

Overview

This example shows how to:

• Initialize the Flagship SDK in a Fastly Compute@Edge environment
• 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 edge application performs the following operations:

1. Retrieves Flagship credentials from the Fastly Secret Store
2. Loads cached bucketing data from Fastly KV storage
3. Initializes the Flagship SDK in decision API 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 Fastly account with Compute@Edge access
• A Flagship account with API credentials

Setup

1. Clone this repository
2. Install dependencies:

yarn install

3. Create a FLAGSHIP_CONFIG.json file in your project root with your credentials:

{
  "envId": "your-env-id",
  "apiKey": "your-api-key"
}

4. For production deployment, create a secret store with your Flagship configuration:

# Create a secret store
fastly compute secret-store create --name=MY_APP_SECRET

# Add your configuration as a secret
fastly compute secret create --store=MY_APP_SECRET --name=FLAGSHIP_CONFIG --file=./FLAGSHIP_CONFIG.json

5. Update the fastly.toml file with your service configuration

Secret Store Configuration

This project uses Fastly's Secret Store to securely manage Flagship credentials. The implementation:

1. Retrieves a JSON configuration containing both environment ID and API key as a single secret
2. Uses this approach to minimize secret reads (Fastly limits to 5 secret reads per request)
3. Configures a local secret store for development in fastly.toml

For local development, the configuration is read from your local FLAGSHIP_CONFIG.json file:

[local_server.secret_stores]
  [[local_server.secret_stores.MY_APP_SECRET]]
    key = "FLAGSHIP_CONFIG"
    file = "./FLAGSHIP_CONFIG.json"

Use KV storage or direct integration for bucketing data

Bucketing data contains information about your Flagship campaigns and variations, allowing the edge application to make flag decisions 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. Configure your local development environment to use this data by adding the following to your fastly.toml file:

[local_server.kv_stores]
  [[local_server.kv_stores.MY_APP_KV]]
    key = "initialBucketing"
    file = "./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 edge application code

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

Then modify your code to import the data directly:

import bucketingData from './bucketing-data.json';

// Then in your initialization code:
await Flagship.start(FLAGSHIP_ENV_ID, FLAGSHIP_API_KEY, {
  decisionMode: DecisionMode.BUCKETING_EDGE,
  initialBucketing: bucketingData,
  fetchNow: false,
  logLevel: LogLevel.DEBUG,
});

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.

For more details on managing KV stores, refer to the Fastly KV Store documentation.

Local Development

Start a local development server:

yarn start

Building and Deployment

Build the project:

yarn build

Deploy to Fastly:

yarn deploy

Learn More

• Flagship Documentation
• Fastly Compute@Edge Documentation
• Fastly CLI Documentation
• Fastly Secret Store Documentation