Basestack Providers for OpenFeature SDKs

OpenFeature providers that talk to the BaseStack flags API from Node.js services and browser applications. The package exposes two purpose-built providers and a thin shared core so you can adopt BaseStack-managed flags everywhere while staying compliant with the OpenFeature specification.

• ✅ Works with the official @openfeature/server-sdk and @openfeature/web-sdk
• ⚡️ Built with Bun + tsdown for a small, ESM-only artifact
• 🧪 Comes with Vitest and Biome configs so the package is ready for CI

Installation

bun add @basestack/openfeature-provider 
# or npm, yarn etc

The package is ESM-only and targets runtimes that provide fetch (Node.js 18+, Bun, modern browsers). Supply a custom fetch implementation if you run on older environments.

Usage

Server runtimes

import { OpenFeature } from "@openfeature/server-sdk";
import { createBasestackServerProvider } from "@basestack/openfeature-provider/server";

OpenFeature.setProvider(
  createBasestackServerProvider({
    projectKey: process.env.BASESTACK_PROJECT_KEY!,
    environmentKey: process.env.BASESTACK_ENVIRONMENT_KEY!,
    // apiUrl: "https://flags-api.basestack.co/v1", // override for self-hosted gateways
    cacheTtlMs: 30_000,
    refreshIntervalMs: 15_000,
  }),
);

const client = OpenFeature.getClient("flags");
const enabled = await client.getBooleanValue("beta-dashboard", false);

Web runtimes

import { OpenFeature } from "@openfeature/web-sdk";
import { createBasestackWebProvider } from "@basestack/openfeature-provider/web";

await OpenFeature.setProviderAndWait(
  createBasestackWebProvider({
    projectKey: window.BASESTACK_PROJECT_KEY,
    environmentKey: window.BASESTACK_ENVIRONMENT_KEY,
    refreshIntervalMs: 60_000, // keep the in-memory snapshot in sync
  }),
);

const client = OpenFeature.getClient("web-flags");
const currentTheme = client.getStringValue("theme", "light");

Shared options

| Option | Type | Default | Description | | --- | --- | --- | --- | | projectKey | string | required | Project identifier used to authorize requests. | | environmentKey | string | required | Environment identifier used to scope flags. | | apiUrl | string | https://flags-api.basestack.co/v1 | Override when self-hosting the BaseStack API. | | cacheTtlMs | number | 30_000 (server) / Infinity (web) | How long a cached flag stays fresh. Set to 0 to disable caching. | | refreshIntervalMs | number | 0 (server) / 30_000 (web) | Background refresh cadence. | | prefetch | boolean | false (server) / true (web) | Fetch the full flag snapshot during initialize. | | requestTimeoutMs | number | 5_000 | Client-side timeout for each HTTP request. | | headers | Record<string, string> | {} | Additional headers merged into every request. | | fetch | (input, init) => Promise<Response> | global fetch | Supply your own fetch implementation when needed. |

Both providers cache the GET /flags snapshot in memory, respect the TTL you configure, and fall back to the caller-provided default value if your BaseStack API is unreachable.

Development

bun install           # download dependencies
bun test              # run Vitest
bun run lint          # Biome lint
bun run format        # Biome format
bun run build         # tsdown build → dist/

The build script bundles every entry point (index, server, and web) into the dist/ directory alongside type declarations so this package can be published to npm under the MIT license.