@splitsoftware/vercel-integration-utils

Vercel integration using Edge Config and Split SDK

Overview

This package provides a Split Storage Wrapper for Vercel Edge Config, a low latency data storage used to store and retrieve feature flag definitions for running the Split SDK on the Edge.

Keeping feature flag definitions within an Edge Config instance enables the Split SDK to operate in partial consumer mode. This mode means that the SDK doesn't fetch feature flags from the Split backend, and instead relies on those stored in the Edge Config, thereby significantly reducing the latency during feature flag evaluations.

The package includes the storage wrapper module (src/EdgeConfigWrapper.ts), as well as an example folder to quickly get started with the integration.

The project overall architecture is illustrated in the following diagram:

Setup

1. Install the Split integration for Vercel to start synchronizing feature flag definitions into your Edge Config instance.
2. Setup the Split SDK in your application project:
   • Install dependencies: npm install @splitsoftware/splitio-browserjs @splitsoftware/vercel-integration-utils @vercel/edge-config
   • Import and use the Split SDK with the EdgeConfig wrapper in your Edge function or middleware (check API route example here):

   import { SplitFactory, PluggableStorage, ErrorLogger } from '@splitsoftware/splitio-browserjs';
   import { EdgeConfigWrapper } from '@splitsoftware/vercel-integration-utils';
   import { createClient } from '@vercel/edge-config';
   
   // Deploying as an Edge function here, but you can also use it on Edge middlewares and Serverless functions
   export const config = { runtime: "edge" };
   
   // Creates a client which knows how to read from Edge Config
   // This client is defined outside of the handler so that it can be reused across requests
   const edgeConfigClient = createClient(process.env.EDGE_CONFIG);
   
   export default async function handler(req, event) {
     // Extract user key. In this case from a request query param
     const { searchParams } = new URL(req.url);
     const userKey = searchParams.get('userKey');
   
     const client = SplitFactory({
       core: {
         authorizationKey: '<YOUR_SPLIT_SDK_KEY>',
         key: userKey
       },
       mode: 'consumer_partial',
       storage: PluggableStorage({
         wrapper: EdgeConfigWrapper({
           // The Edge Config item where Split stores feature flag definitions, specified in the Split integration step
           edgeConfigItemKey: '<YOUR_EDGE_CONFIG_ITEM_KEY>',
           // The Edge Config client
           edgeConfig: edgeConfigClient,
         })
       }),
       // Disable or keep only ERROR log level in production, to minimize performance impact
       debug: ErrorLogger()
     }).client();
   
     // Wait until the SDK is ready or timed out. If timeout occurs, treatment evaluations will default to 'control'.
     // A timeout should not occur if Edge Config is properly configured and synchronized.
     await new Promise(res => {
       client.on(client.Event.SDK_READY, res);
       client.on(client.Event.SDK_READY_TIMED_OUT, res);
     });
   
     const treatment = await client.getTreatment('SOME_FEATURE_FLAG');
   
     // Flush impressions asynchronously. Avoid 'await' on the destroy call, to not delay the response.
     event.waitUntil(client.destroy());
   
     return new Response(JSON.stringify({ treatment }), {
       status: 200,
       headers: { 'content-type': 'application/json' }
     });
   }

   • Remember to update the Split SDK key and Edge Config item key in the code above.
3. Deploy your application to Vercel and test the integration.

Advanced use cases

Provide an Edge Config connection string

By default, the Edge Config client access an Edge Config instance using the Connection String stored in the EDGE_CONFIG environment variable. That variable is automatically set by Vercel when you connect the Edge Config to your project via the Vercel Dashboard.

However, you might require to use a different Edge Config instance, for example, if the default one is used for storing other data. In that case, you can create an Edge Config client with a different connection string, as shown below:

import { createClient } from '@vercel/edge-config';

const client = SplitFactory({
  ...
  storage: PluggableStorage({
    wrapper: EdgeConfigWrapper({
      edgeConfigItemKey: '<YOUR_EDGE_CONFIG_ITEM_KEY>',
      edgeConfig: createClient('<YOUR-EDGE-CONFIG-CONNECTION-STRING>')
    })
  })
});