Basestack adapter for the Vercel Flags SDK

A tiny helper that connects Basestack's Feature Flags API to the Vercel Flags SDK. It exposes a ready-to-use adapter so you can keep using the SDK primitives you already know while letting Basestack act as your remote flag source.

Features

• ✅ Ships as an adapter the SDK can plug into immediately
• 🚀 Bundled with tsdown for small ESM/CJS artifacts and .d.ts files
• 🧪 Tested with Vitest and formatted/linted with Biome
• ⚙️ Supports payload or boolean style flags with customizable value resolvers
• 🧠 Uses a tiny cache and optional warm-up to avoid calling your API more than needed

Installation

bun add flags @basestack/vercel-flags-sdk-adapter
# or npm/pnpm/yarn if you prefer

Usage

Create a single adapter instance and reuse it across your flag() definitions. Provide your Basestack project/environment keys and (optionally) a resolveValue callback to coerce the API payload to the shape your application expects.

// app/flags.ts
import { flag } from "flags/next";
import { createBasestackAdapter } from "@basestack/vercel-flags-sdk-adapter";

const basestack = createBasestackAdapter<boolean>({
  projectKey: process.env.BASESTACK_PROJECT_KEY!,
  environmentKey: process.env.BASESTACK_ENVIRONMENT_KEY!,
  resolveValue: (flag) => flag.enabled
});

export const onboardingFlowFlag = flag<boolean>({
  key: "onboarding-flow",
  adapter: basestack,
  defaultValue: false,
  description: "Enables the streamlined onboarding journey"
});

Whenever the SDK evaluates onboardingFlowFlag() it will call your Basestack API at https://flags-api.basestack.co/v1/flags/{slug}. Successful responses are cached for 30 seconds by default, so subsequent evaluations during a single request won't issue extra network calls.

Adapter options

Option	Type	Default	Description
projectKey	string	—	Required. Basestack project key sent via the x-project-key header.
environmentKey	string	—	Required. Basestack environment key sent via the x-environment-key header.
endpoint	string	https://flags-api.basestack.co/v1	Override when pointing to a different deployment (provide the API base; the client appends /flags paths automatically).
fetch	typeof fetch	globalThis.fetch	Provide a custom fetch implementation (e.g. undici) when running outside Node 18+/Bun.
resolveValue	(flag) => Value	flag.payload ?? flag.enabled	Maps the raw Basestack flag document to the value returned by the SDK.
cacheTtlMs	number	30_000	Amount of time (ms) a resolved flag should be cached in memory. Set to 0 to disable.
requestTimeoutMs	number	—	Aborts fetch calls after the configured timeout.
headers	HeadersInit	—	Additional headers merged into every request.
prefetch	`'none'	'all'`	'none'
onError	(error) => void	—	Observe API/transform errors (the adapter still resolves undefined so the SDK can fall back to defaults).
identify	Identify<Entities>	—	Pass-through to the SDK when you also need custom entity detection logic.

Working with payloads

Basestack flags can store arbitrary JSON payloads. You can keep them as-is, transform them, or only look at the enabled state depending on the needs of each flag.

const productCopyAdapter = createBasestackAdapter<string>({
  projectKey,
  environmentKey,
  resolveValue: (flag) => String(flag.payload ?? "")
});

export const productCopy = flag<string>({
  key: "product-copy",
  adapter: productCopyAdapter,
  defaultValue: ""
});

Using the client directly

If you ever need raw access to the API (for example to seed server components) you can import the BasestackFlagsClient directly:

import { BasestackFlagsClient } from "@basestack/vercel-flags-sdk";

const client = new BasestackFlagsClient({ projectKey, environmentKey });
const flags = await client.listFlags();

The client uses the same headers/caching behavior as the adapter and is fully typed.

Development

This repository is set up with Bun 1.3.2 as the package manager/runtime and comes with everything needed to ship a polished package.

bun install        # install dependencies
bun run lint:all   # run Biome linting
bun run format     # format the codebase
bun run test       # execute the Vitest suite
bun run build      # build the distributable with tsdown

The output of bun run build lives in dist/ and includes both ESM (.mjs), CJS (.cjs), and d.ts artifacts ready to be published to npm under the MIT license.

Framework examples

Need a starting point? Check the framework-specific snippets under examples/:

• next-app-router – evaluates flags inside React Server Components
• next-pages-router – passes the classic req object into the SDK
• svelte-kit – resolves flags during +page.server.ts loads