Fastly SDK reference

This topic documents how to get started with the Fastly SDK, and links to reference information on all of the supported features.

Development work on the Fastly SDK is ongoing. The SDK is fully tested and we consider it production-ready, however, we are actively soliciting feedback on its usage. Some external APIs could change prior to the v1 release.

Overview

This topic documents how to get started with the Fastly SDK, and links to reference information on all of the supported features.

LaunchDarkly’s SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

Resource	Location
SDK API documentation	SDK API docs
Supported SDK Versions	Fastly SDK
GitHub repository	LaunchDarkly Fastly SDK
Sample application	Example app
Published module	npm

Configure the Fastly integration to use this SDK successfully. To learn more, read Fastly.

The Fastly integration is only available to customers on select plans. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Get started

After you complete the Create a Fastly integration process in an existing project, follow these instructions to start using the LaunchDarkly Fastly SDK:

• Install the SDK
• Initialize the client
• Evaluate a flag

Install the SDKFirst, install the Fastly SDK as a dependency in your application using your application’s dependency manager. Here’s how:

yarn

    yarn add @launchdarkly/fastly-server-sdk

Next, import the LaunchDarkly client in your application code:

Import

    import { KVStore } from 'fastly:kv-store';
    import { init } from '@launchdarkly/fastly-server-sdk';

Initialize the client

After you install and import the SDK, configure a Fastly KV Store. Then, initialize an LDClient using your LaunchDarkly client-side ID, the Fastly KV store name, and the Fastly events backend name. The client must be initialized when processing requests.

Here’s how:

Initialize the client

    const KV_STORE_NAME = 'launchdarkly';
    const EVENTS_BACKEND_NAME = 'launchdarkly';
    const store = new KVStore(KV_STORE_NAME);

    async function handleRequest(event: FetchEvent) {
      const ldClient = init('example-client-side-id', store, {
        eventsBackendName: EVENTS_BACKEND_NAME,
      });

      await ldClient.waitForInitialization();

      // The rest of your handler code goes here
    }

The client must be initialized and used when processing requests, not during built-time initialization.

The Fastly SDK requires a client-side ID. Client-side IDs are specific to each project and environment. They are not secret, and you can include them in code. Do not embed a server-side SDK key into an edge application.

You can find client-side IDs in Project settings, on the Environments list. To learn more about key types, read Keys.

Events are enabled by default in the Fastly SDK, which means the Fastly SDK supports Experimentation and metrics use cases by default. To learn more, read Experimentation and metric events.

Evaluate a flag

After you initialize the client, wait for the waitForInitialization function to resolve. When waitForInitialization is resolved, the client can serve feature flags.

Using the client, you can check which variation a particular context will receive for a given feature flag. In your Fastly application, place the variation code so that it is invoked as needed.

Here is an example:

Evaluate a flag

    import type { LDContext } from '@launchdarkly/js-server-sdk-common';

    const ldContext: LDContext = {
      kind: 'org',
      key: 'example-organization-key',
      someAttribute: 'example-attribute-value',
    }
    const flagValue = await ldClient.variation('example-flag-key', ldContext, false)

The SDK caches all KV data during initialization to reduce the number of backend requests needed to fetch KV data. This means changes to feature flags or segments will not be picked up during the lifecycle of a single request instance.

Flush events

You must flush events before your worker exits to ensure that they are sent back to LaunchDarkly. To learn more, read Flushing events.

Supported features

• Anonymous contexts and users
• Configuration
• Context configuration
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Logging configuration
• Secure mode
• Sending custom events