Eppo Developer Tools - Chrome Extension

The Eppo Developer Tools Chrome Extension allows you to instantly override flag assignments for your local user in a shared environment, such as staging or production. This helps you easily QA features by enabling and disabling flags as needed and testing the resulting experience.

Installation

To install Eppo's Chrome Extension, navigate to the Eppo Developer Tools extension on the Chrome Web Store and click Add to Chrome.

Next, create a Browser Extension Key in Eppo by navigating to Flags > Environments > Browser Extension Keys. Create a new Browser Extension Key, give it a name, and select an environment. Copy the key to your clipboard once it has been created, and paste it in in the "Settings" page of your browser extension. Click Save once you have pasted in your key.

Click Back to feature flags list to view your list of flags. Click the refresh icon in the extension's header if they don't immediately appear. At this point, you'll be able to see a list of your flags, but will not yet be able to override them. Follow the instructions below to enable overrides for client or server configuration.

Configuring Client Overrides

Available in @eppo/js-client-sdk@v3.11.0 and later

To configure overriding client-side flags, ensure you have configured a storage key. You can name this however you'd like.

During your client-side SDK initialization, make sure you specify the overridesStorageKey with the same value as your Storage Key setting in your extension.

import { init } from '@eppo/js-client-sdk';

init({
  apiKey: '<your-sdk-key>',
  assignmentLogger: {
    logAssignment(assignment) {
      console.log('TODO: log', assignment);
    },
  },
  overridesStorageKey: 'eppo-overrides', // your overrides key goes here
});

That's it! You should be able to override flag assignments by clicking on the variations in your flags list in the chrome extension.

Configuring Server Overrides

Available in @eppo/node-server-sdk@v3.8.0 and later

With Eppo Developer Tools, you have the option to configure your extension to override server-side flags.

To do so, you'll first need to specify which server-side URLs you want to receive your flag overrides. The Chrome extension intercepts all browser requests that match these URL filters and sends both your browser extension key and your flag overrides in the x-eppo-overrides header so that they can be applied on the server.

Note that since the x-eppo-overrides header also includes your browser extension key, only trusted URLs should be added.

Configuring your middleware

You'll also need to add middleware to process and apply the overrides. You can leverage Node's AsyncLocalStorage to store your flag overrides so that it is available anywhere in your application, but scoped only to the request so that overrides are not applied to other users. The parseOverrides function available in the @eppo/node-server-sdk package will validate and parse the overrides from the x-eppo-overrides header. The withOverrides function will process the overrides and return a client instance with overrides applied.

Putting this all together, an example using NestJS middleware and TypeScript might look like this.

// eppo-overrides-middleware.ts

import { AsyncLocalStorage } from 'async_hooks';
import { FlagKey, Variation } from '@eppo/js-client-sdk-common';
import * as EppoSDK from '@eppo/node-server-sdk';
import { Injectable, NestMiddleware } from '@nestjs/common';
import { NextFunction, Request, Response } from 'express';

export const eppoOverridesStorage = new AsyncLocalStorage<Record<FlagKey, Variation> | undefined>();

@Injectable()
export class EppoOverridesMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const eppoOverridesPayload = req.headers['x-eppo-overrides'] as string | undefined;
    if (eppoOverridesPayload) {
      getInstance()
        .parseOverrides(eppoOverridesPayload)
        .then((overrides) => eppoOverridesStorage.run(overrides, next))
        .catch((err) => {
          console.error('overrides error', err);
          next();
        });
    } else {
      next();
    }
  }
}

// Use this function instead of `EppoSDK.getInstance()` throughout
// your app to apply overrides when they exist in the request.
export const getEppoInstance = () => {
  const overrides = eppoOverridesStorage.getStore();
  return EppoSDK.getInstance().withOverrides(overrides);
};

Once configured, flags that are used in server-side code can be overridden using the Eppo Developer Tools extension without affecting other users connecting to the same web server.