🚩 flaggo

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

Flaggo is designed for developers who want the power of feature flags without the weight of a dedicated server, complex dashboard, or expensive subscription. Just a flags.json file and you're good to go.

🚀 Vision

In a world of complex microservices and heavy SaaS solutions, Flaggo brings back simplicity. By using a simple JSON file as a source of truth, you can manage rollouts, A/B tests, and environment-specific features across your entire stack (Frontend, Backend, and even different languages) with guaranteed consistency.

📦 Installation

# JavaScript / TypeScript (Node.js, Browser, React, Angular, etc.)
npm install flaggo

# Python
pip install flaggo-python

# Rust
cargo add flaggo-rust

🛠 Usage

1. Define your flags (flags.json)

{
  "flags": {
    "new-ui": {
      "enabled": true,
      "environments": ["production"],
      "rollout": 50
    },
    "header-style": {
      "enabled": true,
      "variants": {
        "modern": 0.5,
        "classic": 0.5
      }
    }
  }
}

💻 JavaScript / TypeScript

Standard usage for Node.js or Browser.

import { Flaggo } from "flaggo";

async function main() {
  const flags = await Flaggo.load({
    source: "https://config.example.com/flags.json",
    cacheTTL: 600,
    environment: "production",
    context: { userId: "user-123" },
    fetchOptions: {
      headers: { "Authorization": "Bearer YOUR_TOKEN" } // Cloud Readiness
    }
  });

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

⚡ Edge (Vercel Edge, Cloudflare Workers)

For Edge runtimes, use the lightweight entrypoint that excludes Node.js system APIs.

import { Flaggo } from "flaggo/edge";

// Usage remains identical to standard Flaggo

🐍 Python

from flaggo import Flaggo

# Load with custom headers for authenticated APIs
flags = Flaggo.load(
    source="https://api.flaggo.cloud/v1/flags.json", 
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    cache_ttl=300,
    context={"userId": "user-123"}
)

🐹 Go

import "github.com/FabienOnnis/flaggo/flaggo-go"

flags, err := flaggo.Load(flaggo.FlaggoOptions{
    Source:  "https://api.flaggo.cloud/v1/flags.json",
    Headers: map[string]string{"Authorization": "Bearer YOUR_TOKEN"},
    Context: flaggo.FlagContext{UserID: "user-123"},
})

🦀 Rust

use flaggo_rust::{Flaggo, FlaggoOptions, Source, FlagContext};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut headers = HashMap::new();
    headers.insert("Authorization".to_string(), "Bearer YOUR_TOKEN".to_string());

    let flags = Flaggo::load(FlaggoOptions {
        source: Source::Url("https://api.flaggo.cloud/v1/flags.json".to_string()),
        headers: Some(headers),
        ..Default::default()
    })?;
    
    Ok(())
}

✨ Key Features

• 🎯 Zero-config: No database, no server, no latency. Just a JSON file.
• 🌍 Universal: Native support for Node.js, Browsers, Python, Go and Rust.
• ⚡ Edge Optimized: Dedicated lightweight build for Edge runtimes.
• 🧪 A/B Testing: Native support for variants and weighted distribution.
• ⚡ Smart Cache: Built-in TTL caching with manual refresh capabilities.
• 🔗 Cross-Language Consistency: Guaranteed identical decisions across all SDKs thanks to FNV-1a hashing.
• 🛡️ Environment-aware: Easily filter flags based on your current environment.
• 📈 Stable Rollouts: Incremental rollouts that stay consistent for the same user.

🗺 Roadmap

• [x] v1.x: Initial Core, Universal support, Multi-SDK, Variants & Cache.
• [x] v2.0: Edge Support (JS/TS) & Cloud Readiness (Auth headers across all SDKs).
• [x] v3.0: Major Restructuring (Monorepo) & Independent Package Naming.
• [ ] v3.1: Flaggo Cloud - Management Dashboard (Separate repository).
• [ ] v4.0: Real-time push updates via WebSockets.

🤝 Contributing

Contributions are welcome! Whether it's a new SDK, a bug fix, or a feature request, feel free to open an issue or a PR.

📄 License

Distributed under the MIT License. See LICENSE for more information.