@eppo/node-server-sdk

Eppo Node SDK

Eppo is a modular flagging and experimentation analysis tool. Eppo's Node SDK is built to make assignments in multi-user server side contexts. Before proceeding you'll need an Eppo account.

Features

• Feature gates
• Kill switches
• Progressive rollouts
• A/B/n experiments
• Mutually exclusive experiments (Layers)
• Dynamic configuration

Installation

npm install @eppo/node-server-sdk

Quick start

Begin by initializing a singleton instance of Eppo's client. Once initialized, the client can be used to make assignments anywhere in your app.

Initialize once

import { init } from "@eppo/node-server-sdk";

await init({ apiKey: "<SDK-KEY-FROM-DASHBOARD>" });

Assign anywhere

import * as EppoSdk from "@eppo/node-server-sdk";

const eppoClient = EppoSdk.getInstance();

// Hypothetical user.
const user = getCurrentUser();

const variation = eppoClient.getStringAssignment(
  'new-user-onboarding', 
  user.id, 
  { country: user.country }, 
  'control'
);

Assignment functions

Every Eppo flag has a return type that is set once on creation in the dashboard. Once a flag is created, assignments in code should be made using the corresponding typed function:

getBoolAssignment(...)
getNumericAssignment(...)
getIntegerAssignment(...)
getStringAssignment(...)
getJSONAssignment(...)

Each function has the same signature, but returns the type in the function name. For booleans use getBooleanAssignment, which has the following signature:

getBoolAssignment: (
  flagKey: string,
  subjectKey: string,
  subjectAttributes: Record<string, any>,
  defaultValue: boolean,
) => boolean

Initialization options

The init function accepts the following optional configuration arguments.

Option	Type	Description	Default
assignmentLogger	IAssignmentLogger	A callback that sends each assignment to your data warehouse. Required only for experiment analysis. See example below.	null
requestTimeoutMs	number	Timeout in milliseconds for HTTPS requests for the experiment configurations.	5000
numInitialRequestRetries	number	Number of additional times the initial configurations request will be attempted if it fails. This is the request typically synchronously waited (via await) for completion. A small wait will be done between requests.	1
pollAfterFailedInitialization	boolean	Poll for new configurations even if the initial configurations request failed.	false
throwOnFailedInitialization	boolean	Throw an error (reject the promise) if unable to fetch initial configurations during initialization.	true
numPollRequestRetries	number	If polling for updated configurations after initialization, the number of additional times a request will be attempted before giving up. Subsequent attempts are done using an exponential backoff.	7

Assignment logger

To use the Eppo SDK for experiments that require analysis, pass in a callback logging function to the init function on SDK initialization. The SDK invokes the callback to capture assignment data whenever a variation is assigned. The assignment data is needed in the warehouse to perform analysis.

The code below illustrates an example implementation of a logging callback using Segment, but you can use any system you'd like. The only requirement is that the SDK receives a logAssignment callback function. Here we define an implementation of the Eppo IAssignmentLogger interface containing a single function named logAssignment:

import { IAssignmentLogger } from "@eppo/node-server-sdk";
import { AnalyticsBrowser } from "@segment/analytics-next";

// Connect to Segment (or your own event-tracking system)
const analytics = AnalyticsBrowser.load({ writeKey: "<SEGMENT_WRITE_KEY>" });

const assignmentLogger: IAssignmentLogger = {
  logAssignment(assignment) {
    analytics.track({
      userId: assignment.subject,
      event: "Eppo Assignment",
      type: "track",
      properties: { ...assignment },
    });
  },
};

Export configuration

To support the use-case of needing to bootstrap your front-end client with an Eppo Client SDK, the Eppo NodeJS SDK provides a function to export flag configurations.

Use the getFlagConfigurations(): Record<string, Flag> function to export flag configurations, stringify them (or your preferred serialization method), and send it to the front-end client as a part of your routine initialization.

import express from 'express';
import * as EppoSdk from "@eppo/node-server-sdk";

const app = express();
const eppoClient = EppoSdk.getInstance();

app.get('/api/flag-configurations', (req, res) => {
  const flagConfigurations = eppoClient.getFlagConfigurations();
  res.json(flagConfigurations);
});

Philosophy

Eppo's SDKs are built for simplicity, speed and reliability. Flag configurations are compressed and distributed over a global CDN (Fastly), typically reaching your servers in under 15ms. Server SDKs continue polling Eppo’s API at 30-second intervals. Configurations are then cached locally, ensuring that each assignment is made instantly. Evaluation logic within each SDK consists of a few lines of simple numeric and string comparisons. The typed functions listed above are all developers need to understand, abstracting away the complexity of the Eppo's underlying (and expanding) feature set.