How to use local evaluation for low-latency feature flags in Node.js

npm install @amplitude/experiment-node-server

AMPLITUDE_API_KEY=your-project-api-key
AMPLITUDE_DEPLOYMENT_KEY=your-server-deployment-key

import { Experiment, LogLevel } from '@amplitude/experiment-node-server';

const deploymentKey = process.env.AMPLITUDE_DEPLOYMENT_KEY;
const apiKey = process.env.AMPLITUDE_API_KEY;

if (!deploymentKey) {
  throw new Error('AMPLITUDE_DEPLOYMENT_KEY is not set');
}
if (!apiKey) {
  throw new Error('AMPLITUDE_API_KEY is not set');
}

export const localFlags = Experiment.initializeLocal(deploymentKey, {
  // Amplitude pushes flag changes to the process, generally in under a second.
  streamUpdates: true,
  // If the stream fails, the SDK falls back to polling at this interval.
  flagConfigPollingIntervalMillis: 30000,
  // The project API key (not the deployment key) for exposure events.
  exposureConfig: { apiKey },
  logLevel:
    process.env.NODE_ENV === 'production' ? LogLevel.Warn : LogLevel.Debug,
});

// Evaluates one flag for one request in memory. Returns null when there's
// nothing to evaluate or evaluation fails, so callers serve the default.
export function evaluateFlag(flagKey, ids, userProperties = {}) {
  // The flag buckets by device ID; without one, serve the default.
  if (!ids.device_id) return null;

  try {
    const variants = localFlags.evaluateV2(
      { ...ids, user_properties: userProperties },
      [flagKey],
      { tracksExposure: true },
    );
    return variants[flagKey] ?? null;
  } catch (err) {
    console.warn(`[flags] ${flagKey} evaluation failed, serving default:`, err?.message);
    return null;
  }
}

import express from 'express';
import { amplitude } from './lib/amplitude.js';
import { localFlags } from './lib/local-flags.js';
import { amplitudeIdentity } from './middleware/amplitude-identity.js';
import { auth } from './routes/auth.js';
import { billing } from './routes/billing.js';
import { products } from './routes/products.js';

const app = express();
app.use(express.json());
// Mount your session or auth middleware here, before amplitudeIdentity,
// so req.user is populated.
app.use(amplitudeIdentity);
app.use('/auth', auth);
app.use('/billing', billing);
app.use('/products', products);

try {
  // Load flag rules before taking traffic.
  await localFlags.start();
} catch (err) {
  // Keep serving if Amplitude is unreachable at boot; routes fall back
  // to their defaults until rules load.
  console.warn('[flags] could not load flag configs, serving defaults:', err?.message);
}

const port = Number(process.env.PORT ?? 3000);
const server = app.listen(port, () => {
  console.log(`Listening on ${port}`);
});

async function shutdown(signal) {
  console.log(`${signal} received, flushing Amplitude`);
  server.close();
  await amplitude.flush().promise;
  process.exit(0);
}

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

import { Router } from 'express';
import { evaluateFlag } from '../lib/local-flags.js';

export const products = Router();

// Stand-in for your catalog query.
const PRODUCTS = [
  { id: 'prod-1001', name: 'Starter kit', createdAt: '2026-09-28', unitsSold: 120 },
  { id: 'prod-1002', name: 'Team bundle', createdAt: '2026-08-14', unitsSold: 940 },
  { id: 'prod-1003', name: 'Pro add-on', createdAt: '2026-10-02', unitsSold: 310 },
];

const SORTS = {
  newest: (a, b) => b.createdAt.localeCompare(a.createdAt),
  popularity: (a, b) => b.unitsSold - a.unitsSold,
};

products.get('/', (req, res) => {
  // Local evaluation only sees the properties you pass in.
  const userProperties = req.user ? { plan: req.user.plan } : {};
  const variant = evaluateFlag('product-list-sort', req.amplitudeIds, userProperties);
  const sort = variant?.value === 'popularity' ? 'popularity' : 'newest';

  res.json({ sort, items: [...PRODUCTS].sort(SORTS[sort]) });
});

curl http://localhost:3000/products \
  -H 'x-amplitude-device-id: test-device-12345'

// -- .env --
AMPLITUDE_API_KEY=your-project-api-key
AMPLITUDE_DEPLOYMENT_KEY=your-server-deployment-key

// -- lib/local-flags.js --
import { Experiment, LogLevel } from '@amplitude/experiment-node-server';

const deploymentKey = process.env.AMPLITUDE_DEPLOYMENT_KEY;
const apiKey = process.env.AMPLITUDE_API_KEY;

if (!deploymentKey) {
  throw new Error('AMPLITUDE_DEPLOYMENT_KEY is not set');
}
if (!apiKey) {
  throw new Error('AMPLITUDE_API_KEY is not set');
}

export const localFlags = Experiment.initializeLocal(deploymentKey, {
  streamUpdates: true,
  flagConfigPollingIntervalMillis: 30000,
  exposureConfig: { apiKey },
  logLevel:
    process.env.NODE_ENV === 'production' ? LogLevel.Warn : LogLevel.Debug,
});

export function evaluateFlag(flagKey, ids, userProperties = {}) {
  if (!ids.device_id) return null;

  try {
    const variants = localFlags.evaluateV2(
      { ...ids, user_properties: userProperties },
      [flagKey],
      { tracksExposure: true },
    );
    return variants[flagKey] ?? null;
  } catch (err) {
    console.warn(`[flags] ${flagKey} evaluation failed, serving default:`, err?.message);
    return null;
  }
}

// -- routes/products.js --
import { Router } from 'express';
import { evaluateFlag } from '../lib/local-flags.js';

export const products = Router();

const PRODUCTS = [
  { id: 'prod-1001', name: 'Starter kit', createdAt: '2026-09-28', unitsSold: 120 },
  { id: 'prod-1002', name: 'Team bundle', createdAt: '2026-08-14', unitsSold: 940 },
  { id: 'prod-1003', name: 'Pro add-on', createdAt: '2026-10-02', unitsSold: 310 },
];

const SORTS = {
  newest: (a, b) => b.createdAt.localeCompare(a.createdAt),
  popularity: (a, b) => b.unitsSold - a.unitsSold,
};

products.get('/', (req, res) => {
  const userProperties = req.user ? { plan: req.user.plan } : {};
  const variant = evaluateFlag('product-list-sort', req.amplitudeIds, userProperties);
  const sort = variant?.value === 'popularity' ? 'popularity' : 'newest';
  res.json({ sort, items: [...PRODUCTS].sort(SORTS[sort]) });
});

// -- server.js --
import express from 'express';
import { amplitude } from './lib/amplitude.js';
import { localFlags } from './lib/local-flags.js';
import { amplitudeIdentity } from './middleware/amplitude-identity.js';
import { auth } from './routes/auth.js';
import { billing } from './routes/billing.js';
import { products } from './routes/products.js';

const app = express();
app.use(express.json());
app.use(amplitudeIdentity);
app.use('/auth', auth);
app.use('/billing', billing);
app.use('/products', products);

try {
  await localFlags.start();
} catch (err) {
  console.warn('[flags] could not load flag configs, serving defaults:', err?.message);
}

const port = Number(process.env.PORT ?? 3000);
const server = app.listen(port, () => {
  console.log(`Listening on ${port}`);
});

async function shutdown(signal) {
  console.log(`${signal} received, flushing Amplitude`);
  server.close();
  await amplitude.flush().promise;
  process.exit(0);
}

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

Add Amplitude local evaluation feature flags to this Node.js Express
backend by following https://amplitude.com/build/nodejs-local-evaluation
exactly. It assumes the setup from
https://amplitude.com/build/nodejs-product-analytics is in place; if
req.amplitudeIds doesn't exist yet, do that page first. Use
@amplitude/experiment-node-server and create one client in
lib/local-flags.js with Experiment.initializeLocal, reading
AMPLITUDE_DEPLOYMENT_KEY (a server deployment key) and AMPLITUDE_API_KEY
(the project API key, used only in exposureConfig) from the environment,
with streamUpdates true and flagConfigPollingIntervalMillis 30000. In
server.js, await localFlags.start() inside a try/catch before
app.listen. Evaluate flags only in the route that uses the result, with
evaluateV2(user, [flagKey], { tracksExposure: true }), passing
req.amplitudeIds plus every user property the flag's targeting reads,
and serve a default when there's no device ID, no variant, or an
error. Never evaluate flags in global middleware. Don't hardcode keys,
don't invent flag keys, and don't send the deployment key to the
browser. Report every file you changed and anything I need to add to
.env.