flagd-node

A lightweight, zero-dependency TypeScript client and React Hook library for flagd.

Features

• Type-safe: Written in TypeScript with full interface definitions.
• Fail-safe: isEnabled defaults to false if the server is unreachable.
• React-ready: Includes built-in hooks for easy feature flagging in React apps.
• Lightweight: Zero external dependencies.
• Modern: Uses the Fetch API and AbortController for timeouts.

Installation

npm install @gappylul/flagd
# or
yarn add @gappylul/flagd
# or
bun add @gappylul/flagd

Vanilla JavaScript/TypeScript Usage

import { FlagdClient } from '@gappylul/flagd';

const client = new FlagdClient({
  url: "https://flagd.yourdomain.com",
  timeout: 3000 // optional, defaults to 2000ms
});

// Simple check
const isDark = await client.isEnabled("dark-mode");

// Fetch full flag details
try {
  const flag = await client.get("new-feature");
  console.log(flag.description, flag.enabled);
} catch (err) {
  console.error("Flag not found or server down");
}

React Usage

The SDK exports two hooks for React applications.

useFlagEnabled

Returns a simple boolean. Useful for toggling components or styling.

import { useFlagEnabled } from '@gappylul/flagd';

function App() {
  const isEnabled = useFlagEnabled("new-ui", "https://flagd.gappy.hu");

  return (
    <div className={isEnabled ? "modern-theme" : "legacy-theme"}>
      <h1>Hello World</h1>
    </div>
  );
}

useFlagd

Returns the full flag object, plus loading and error states.

import { useFlagd } from '@gappylul/flagd';

function FeatureBanner() {
  const { flag, loading, error } = useFlagd("banner-promo", "https://flagd.gappy.hu");

  if (loading || error || !flag?.enabled) return null;

  return (
    <div className="banner">
      <h2>{flag.name}</h2>
      <p>{flag.description}</p>
    </div>
  );
}

API Reference

FlagdClient

| Method | Description | |---------------------------|-----------------------------------------------------------| | isEnabled(name: string) | Returns Promise<boolean>. Returns false on any error. | | get(name: string) | Returns Promise<Flag>. Throws error if flag is missing. | | list() | Returns Promise<Flag[]>. Returns all available flags. |

Flag Interface

interface Flag {
  name: string;
  enabled: boolean;
  description: string;
  created_at: string;
  updated_at: string;
}