flagwave

Feature flags for Node.js and TypeScript — create a flag on the dashboard, check it from your code, ship changes without redeploying.

🌐 Website & Dashboard: https://feature-flag-service-l7ru.vercel.app/ 🚀 Live demo: https://feature-flag-service-l7ru.vercel.app/ — sign up, create a project, and flip a flag in under a minute 📖 Docs: https://feature-flag-service-l7ru.vercel.app/docs 📦 npm: https://www.npmjs.com/package/flagwave

New here? Start on the website above: create a free account, create a project, then copy the API key from Project → Settings → API Keys. You'll need that key to use this SDK.

Contents

• What is FlagWave?
• Requirements
• Install
• Quick start
• Configuration
• API
• Browsing flags from the terminal
• Error handling
• Exports
• License

What is flagwave?

FlagWave is a lightweight feature-flag service built for quick, low-friction setup:

• No personal data. A flag is just a name and an on/off state tied to your project — no user tracking, no PII stored.
• Self-cleaning. Every isEnabled check updates a flag's "last used" timestamp. Flags that go unchecked for a long time are treated as stale and automatically cleaned up, so you don't have to manually prune old flags.
• Quick, easy setup. One API key, one HTTP call. No infrastructure to run, no polling service to host yourself.

This package (flagwave) is the official Node.js/TypeScript client for that service.

Requirements

Node.js 18 or later. The SDK uses the built-in fetch and AbortController — no polyfills or extra dependencies needed.

Install

npm install flagwave

Quick start

import { FlagWave } from "flagwave";

const sdk = new FlagWave(process.env.FLAGWAVE_API_KEY!);

if (await sdk.isEnabled("darkMode")) {
  enableDarkMode();
}

Each API key is scoped to a single project. Create one FlagWave instance per key and reuse it for the life of your app — it holds no mutable state beyond the key, base URL, and an internal response cache.

Configuration

Pass an options object as the second constructor argument to tune timeouts and caching:

const sdk = new FlagWave(process.env.FLAGWAVE_API_KEY!, {
  timeoutMs: 5000,   // abort a request if it takes longer than 5s (default: 8000)
  cacheTtlMs: 3000,  // reuse getFlags({ mode: "ALL" }) results for 3s (default: 0 — no caching)
});

API

sdk.isEnabled(name: string): Promise<boolean>

Check whether a single flag is on. This is the method you'll use most day to day — every call also refreshes the flag's "last used" timestamp, which is what keeps an active flag out of the auto-cleanup described above.

if (await sdk.isEnabled("betaCheckout")) {
  renderBetaCheckout();
}

Throws if name is empty, or if the request fails (for example, the flag doesn't exist).

sdk.getFlags({ mode: "ALL" }): Promise<Flag[]>

Fetch every flag in the project in one call:

const flags = await sdk.getFlags({ mode: "ALL" });
console.log(flags.map((f) => f.name));

sdk.getFlags({ mode: "PAGINATED", page, limit }): Promise<PaginatedFlags>

Fetch one page at a time — useful once a project has a lot of flags:

const { flags, page, totalPages } = await sdk.getFlags({
  mode: "PAGINATED",
  page: 1,
  limit: 20,
});

TypeScript infers the right return type automatically based on mode, so no casting is needed at the call site.

Browsing flags from the terminal

The package also ships a small interactive CLI helper, browseFlags, for paging through a project's flags without leaving the terminal:

import { FlagWave, browseFlags } from "flagwave";

const sdk = new FlagWave(process.env.FLAGWAVE_API_KEY!);
await browseFlags(sdk, 10); // 10 flags per page

Once it's running:

| Key | Action | | ----- | ------------- | | n | Next page | | p | Previous page | | q | Quit |

Each flag is printed with a ✓ (enabled) or ✗ (disabled) next to its name.

Error handling

Every method throws a plain Error on failure — there are no custom error classes to import. Network failures, timeouts, and API-level errors (like a missing flag) are all normalized this way, so one try/catch covers everything:

try {
  const enabled = await sdk.isEnabled("darkMode");
} catch (err) {
  console.error((err as Error).message);
}

Exports

| Export | What it is | | -------------------- | ------------------------------------------------------------- | | FlagWave | The client | | browseFlags | Terminal CLI pagination helper | | Flag | Shape of a single flag | | PaginatedFlags | Return type of a paginatedgetFlags call | | FetchFlag | Input type forgetFlags | | IFlagWave | InterfaceFlagWave implements (handy for mocking in tests) | | FlagCacheOptions | Constructor options (timeoutMs, cacheTtlMs) |

License

MIT © laxmiTimsina — see LICENSE for the full text.