Flags SDK

The Flags SDK declares flags in code and evaluates them on the server, in Next.js or SvelteKit. @faststats/flags-sdk is an adapter that resolves those flags from FastStats.

InstallCopy Anchor Link

npm install flags @faststats/flags-sdk

Set FASTSTATS_FLAGS_TOKEN to the project’s token, or to a FastStats API key scoped to the project with the featureFlagEvaluation:evaluate permission:

FASTSTATS_FLAGS_TOKEN=your_project_token

The token is read on the first evaluation, so builds do not need it.

Declare FlagsCopy Anchor Link

import { type FastStatsEntities, fastStatsAdapter } from "@faststats/flags-sdk";
import { dedupe, flag } from "flags/next";

const identify = dedupe(async ({ cookies }): Promise<FastStatsEntities> => ({
	identifier: cookies.get("visitor")?.value,
	userId: cookies.get("user")?.value,
	attributes: { plan: "pro" },
}));

export const newCheckout = flag<boolean, FastStatsEntities>({
	key: "new-checkout",
	adapter: fastStatsAdapter,
	identify,
	defaultValue: false,
});

export const maxUploads = flag<number, FastStatsEntities>({
	key: "max-uploads",
	adapter: fastStatsAdapter,
	identify,
	defaultValue: 10,
});

Then call the flag where you need it:

import { newCheckout } from "../../flags";

export default async function Page() {
	return (await newCheckout()) ? <NewCheckout /> : <OldCheckout />;
}

Each evaluation is recorded as an exposure, so evaluate a flag where you use it.

Identify the VisitorCopy Anchor Link

identify returns who the flag is evaluated for:

The adapter forwards the visitor’s User-Agent, so rules can match browser, os, and device. country is filled from x-vercel-ip-country or cf-ipcountry unless attributes already sets it.

Evaluate Several FlagsCopy Anchor Link

evaluate() resolves flags that share an adapter and identify in one request:

import { evaluate } from "flags/next";

const [checkout, uploads] = await evaluate([newCheckout, maxUploads]);

DefaultsCopy Anchor Link

A flag falls back to its defaultValue when it does not exist, is archived, or the service cannot be reached within timeoutMs. A missing flag without a defaultValue throws a FastStatsFlagsError.

Configure the AdapterCopy Anchor Link

fastStatsAdapter reads its settings from the environment. Use createFastStatsAdapter to set them in code:

import { createFastStatsAdapter } from "@faststats/flags-sdk";

export const fastStatsAdapter = createFastStatsAdapter({
	token: process.env.MY_FLAGS_TOKEN,
	timeoutMs: 1000,
	origin: "https://faststats.dev/project/your-project-slug/feature-flags",
});

FASTSTATS_TOKEN is also accepted when FASTSTATS_FLAGS_TOKEN is not set.