🚩 flaggo (JavaScript / TypeScript SDK)

A minimalist, zero-config, portable feature flag library.

⚠️ Migration Guide (v3.0.0)

Flaggo has moved to a Monorepo structure.

• If you are using JavaScript or TypeScript, no action is needed other than updating to v3.0.0.
• If you were relying on the Python, Go, or Rust source files previously included in this package, they have been moved to their own independent packages:
  • Python: flaggo-python
  • Go: flaggo-go
  • Rust: flaggo-rust

📦 Installation

npm install flaggo

⚡ Quick Start (Edge & Node.js)

import { Flaggo } from "flaggo";

async function main() {
  const flags = await Flaggo.load({
    source: "https://config.example.com/flags.json",
    cacheTTL: 600,            // Cache for 10 minutes
    pollingInterval: 60,      // Optional: Refresh flags every 60s in background
    context: { userId: "user-123" },
    onRefreshError: (err) => console.error("Refresh failed", err)
  });

  if (flags.isEnabled("new-ui")) {
    console.log("New UI is active!");
  }
}

⚛️ React Integration

import { Flaggo, FlaggoProvider, useFlag } from "flaggo/react";

const flaggo = await Flaggo.load({ source: "flags.json" });

function App() {
  return (
    <FlaggoProvider flaggo={flaggo}>
      <MyComponent />
    </FlaggoProvider>
  );
}

function MyComponent() {
  const isEnabled = useFlag("new-feature");
  return isEnabled ? <NewFeature /> : <OldFeature />;
}

✨ Key Features

• 🎯 Zero-config: Just a JSON file.
• ⚡ Edge Optimized: Dedicated lightweight build.
• 🔄 Automatic Polling: Periodic background refresh for long-running apps.
• ⚛️ React Hooks: Native support for React with useFlag and <Flag />.
• 🔗 Cross-Language Consistency: Decisions stay identical across all SDKs.
• 🛡️ Environment-aware: Easily filter flags by environment.

💡 Pro Tips

Master Switch vs. Rules

The enabled property at the root of a flag acts as a Master Switch.

• If enabled: false, the flag is globally disabled and rules are never evaluated.
• For a "disabled by default but enabled for specific users" behavior: set enabled: true and use a final "catch-all" rule that returns false.

🗺️ Roadmap

• [x] Automatic Polling: Background refresh at regular intervals.
• [x] React & Next.js Hooks: Official useFlag() and <Flag /> components.
• [x] Browser DevTools: Extension to inspect and override flags.
• [x] Local Persistence: Cache flags in LocalStorage for instant startup.
• [x] Array Support in contains: Allow the contains operator to check for values within arrays.

💾 Local Persistence

Enable persistence to cache flags in localStorage or sessionStorage. This allows the SDK to return flags immediately on startup while it fetches updates in the background.

const flaggo = await Flaggo.load({
  source: "https://api.example.com/flags.json",
  persist: true // Defaults to localStorage with auto-generated key
});

// Advanced configuration
const flaggo = await Flaggo.load({
  source: "https://api.example.com/flags.json",
  persist: {
    key: "my_custom_cache_key",
    storage: "sessionStorage", // or "localStorage" (default)
    ttl: 3600 // Override cache timeout for persistence in seconds
  }
});

🛠️ DevTools & Overrides

Flaggo includes built-in support for debugging and testing via local overrides.

1. Enable DevTools

Enable enableDevTools to expose your Flaggo instance to the global window.__FLAGGO__ object. This allows browser extensions and console debugging.

const flaggo = await Flaggo.load({
  source: "flags.json",
  enableDevTools: true
});

2. Manual Overrides

You can force a flag to be enabled/disabled or return a specific variant for the current session. Overrides take precedence over all other rules.

// Force enable a flag
flaggo.setOverride("new-feature", true);

// Force a specific variant
flaggo.setOverride("header-style", "modern");

// Remove an override
flaggo.removeOverride("new-feature");

Overrides trigger a refresh of all subscribed components (e.g., React hooks will re-render automatically).

For full documentation and other SDKs, visit the main repository.