Fargo Flags

Enhanced toolkit built on Vercel's Flags SDK with CLI tools, component registry, and streamlined developer experience.

✓ Built on Flags SDK

✓ Enhanced DX

✓ CLI Tools

🤝 Built on Vercel's Flags SDK

Fargo Flags is a thin layer of abstraction that enhances Vercel's Flags SDK with streamlined tooling and distribution. We embrace the same core principles while making them easier to adopt and scale.

🏗️ Flags SDK Foundation

✓Flags as code - declarative definitions with consistent call sites
✓Server-side resolution - secure, performant flag evaluation
✓Type safety - full TypeScript support with runtime validation
✓No vendor lock-in - your flag logic stays in your codebase

🚀 Fargo Enhancements

+Interactive CLI wizard for guided flag creation
+Automatic registry management - no manual imports
+Component registry distribution via shadcn CLI
+Enhanced React components and testing utilities
+Consistency validation for CI/CD pipelines

💡 Why This Approach?

The Flags SDK provides excellent architectural patterns, but setting up the boilerplate and maintaining consistency across a growing codebase can be tedious. Fargo Flags automates the repetitive parts while preserving all the benefits of the "flags as code" approach.

✨ Key Features

🎯 One File Per Flag

Each feature flag lives in its own file with schema, defaults, and decision logic.

🔒 Type Safety

Full TypeScript support with Zod schemas for runtime validation.

🚀 No Build Step

Static imports with checked-in aggregator. No codegen required.

🌐 SSR First

Resolve flags on the server, hydrate client-safe subset.

🔧 Developer Tools

Wizard for creating flags, consistency checker for CI.

🧪 Testing Ready

Test provider for overriding flags in tests and Storybook.

🚀 Getting Started

📦 Installation

1. Install core system:

2. Install CLI tools:

3. Add package.json scripts:

"flags:new": "tsx scripts/create-flag.ts",

"flags:check": "tsx scripts/check-flags-registry.ts"

⚡ Quick Start

1. Create your first flag:

2. Validate consistency:

🧙‍♂️ Interactive Wizard

The CLI wizard guides you through creating flags with prompts for type, default value, client exposure, and more.

🏗️ Architecture & How It Works

📁 Directory Structure

lib/flags/
├── kit.ts                    # Core types
├── runtime.ts                # Server resolver
├── registry.config.ts        # Aggregator
└── defs/                     # Flag definitions
    ├── feature-a.flag.ts
    └── feature-b.flag.ts

components/flags/
├── flags-provider.tsx        # React context
├── flag.tsx                  # Conditional component
└── flags-test-provider.tsx   # Testing utilities

⚡ Resolution Flow

1Define flags in defs/*.flag.ts files

2Wizard updates registry.config.ts automatically

3Server resolves all flags with context

4Client receives safe subset via provider

5Components use hooks or <Flag> wrapper

⚡ resolveAllFlags() Engine

The server-side engine that evaluates all your feature flags and returns their resolved values.

🔄 The Resolution Process

1Gets all flag keys from your registry

2Runs all flags in parallel for performance

3Calls each flag's decide() function with context

4Falls back to defaultValue if no decide function

5Validates results against Zod schemas

🎯 Usage Patterns

Basic Usage

await resolveAllFlags()

Simple flags using defaultValue

With Context

await resolveAllFlags({ getUser, getWorkspace })

Personalized flags with user data

In API Routes

const flags = await resolveAllFlags(ctx)

Server-side flag access

🔒 Security & Performance

Server-Only Execution

All decision logic runs securely on the server

Parallel Processing

All flags resolve simultaneously for speed

🚀 Interactive Demo & Components

Try changing the flag values below to see how they instantly affect the UI components. Plus explore the React components that make working with feature flags seamless.

🤖 AI Assistant Feature

DISABLED

Flag: enable-ai-assistant-in-pdf-toolbar

PDF Document Viewer

Standard PDF viewer without AI-powered features.

🎛️ Try It Yourself

Toggle AI Assistant:

Watch the PDF toolbar update instantly when you toggle this flag!

📄 Pagination Layout

BOTTOM

Flag: pagination-ui-location

📋 Search Result 1

📋 Search Result 2

📋 Search Result 3

... and 47 more results

123

🎛️ Try It Yourself

Change Pagination Location:

See how the pagination controls move around the content area!

🎨 Theme Mode

LIGHT

Flag: theme-mode

Application Header

☀️ Light

☀️ Light mode offers a clean, bright interface perfect for daytime use and maximum readability.

🎛️ Try It Yourself

Change Theme Mode:

Watch the theme change instantly across the entire interface!

🧩 React Components

Fargo Flags comes with several React components to make working with feature flags seamless.

🪝 useFlag Hook

Get flag values directly in your components with full type safety.

const showAssistant = useFlag("enable-ai-assistant-in-pdf-toolbar");

Current value: false

🏷️ <Flag> Component

Conditionally render content based on flag values.

Hidden in dark mode

</Flag>

🔄 FlagsProvider

Integrates with Next.js App Router for SSR-first flag resolution.

const serverFlags = await resolveAllFlags();

const clientFlags = pickClientFlags(serverFlags);

{children}

</FlagsProvider>

🧪 FlagsTestProvider

Override flag values for testing and development.

Test components...

</FlagsTestProvider>

💡 Pro Tip

All components are fully typed! Your IDE will provide autocomplete for flag names and values, catching typos at compile time instead of runtime.

💻 Code Examples

1. Define a Flag

// lib/flags/defs/my-feature.flag.ts
import { z } from "zod";
import { defineFlag } from "../kit";

export const key = "my-awesome-feature" as const;
export const schema = z.boolean();

export default defineFlag({
  key,
  schema,
  description: "Enable my awesome new feature",
  defaultValue: false,
  client: { public: true },
  async decide(ctx) {
    const user = await ctx.getUser?.();
    return user?.plan === "premium";
  },
});

2. Use in Components

import { useFlag } from "@/components/flags/flags-provider";
import { Flag } from "@/components/flags/flag";

function MyComponent() {
  const isEnabled = useFlag("my-awesome-feature");
  
  return (
    <div>
      <h1>My App</h1>
      
      {/* Using the hook */}
      {isEnabled && <NewFeatureButton />}
      
      {/* Using the component */}
      <Flag when="my-awesome-feature">
        <NewFeaturePanel />
      </Flag>
    </div>
  );
}

3. Next.js App Router Integration

// app/layout.tsx (Server Component)
import { resolveAllFlags, pickClientFlags } from "@/lib/flags/runtime";
import { FlagsProvider } from "@/components/flags/flags-provider";

export default async function RootLayout({ children }) {
  // 🚀 resolveAllFlags() runs on the server and:
  // - Calls each flag's decide() function with context
  // - Validates results against Zod schemas  
  // - Returns ALL flags (including server-only ones)
  const serverFlags = await resolveAllFlags({
    getUser: async () => getCurrentUser(),
    getWorkspace: async () => getCurrentWorkspace(),
  });
  
  // 🔒 pickClientFlags() creates client-safe subset:
  // - Only includes flags with client: { public: true }
  // - Applies optional serialize() functions
  // - Excludes sensitive server-only flags
  const clientFlags = pickClientFlags(serverFlags);

  return (
    <html lang="en">
      <body>
        <FlagsProvider flags={clientFlags}>
          {children}
        </FlagsProvider>
      </body>
    </html>
  );
}

4. Testing with Overrides

import { FlagsTestProvider } from "@/components/flags/flags-test-provider";

function MyStory() {
  return (
    <FlagsTestProvider 
      overrides={{ "my-awesome-feature": true }}
    >
      <MyComponent />
    </FlagsTestProvider>
  );
}

🤝 Built on Vercel's Flags SDK

🏗️ Flags SDK Foundation

✓Flags as code - declarative definitions with consistent call sites
✓Server-side resolution - secure, performant flag evaluation
✓Type safety - full TypeScript support with runtime validation
✓No vendor lock-in - your flag logic stays in your codebase

🚀 Fargo Enhancements

+Interactive CLI wizard for guided flag creation
+Automatic registry management - no manual imports
+Component registry distribution via shadcn CLI
+Enhanced React components and testing utilities
+Consistency validation for CI/CD pipelines

💡 Why This Approach?

✨ Key Features

🎯 One File Per Flag

Each feature flag lives in its own file with schema, defaults, and decision logic.

🔒 Type Safety

Full TypeScript support with Zod schemas for runtime validation.

🚀 No Build Step

Static imports with checked-in aggregator. No codegen required.

🌐 SSR First

Resolve flags on the server, hydrate client-safe subset.

🔧 Developer Tools

Wizard for creating flags, consistency checker for CI.

🧪 Testing Ready

Test provider for overriding flags in tests and Storybook.

🚀 Getting Started

📦 Installation

1. Install core system:

2. Install CLI tools:

3. Add package.json scripts:

"flags:new": "tsx scripts/create-flag.ts",

"flags:check": "tsx scripts/check-flags-registry.ts"

⚡ Quick Start

1. Create your first flag:

2. Validate consistency:

🧙‍♂️ Interactive Wizard

The CLI wizard guides you through creating flags with prompts for type, default value, client exposure, and more.

🏗️ Architecture & How It Works

📁 Directory Structure

lib/flags/
├── kit.ts                    # Core types
├── runtime.ts                # Server resolver
├── registry.config.ts        # Aggregator
└── defs/                     # Flag definitions
    ├── feature-a.flag.ts
    └── feature-b.flag.ts

components/flags/
├── flags-provider.tsx        # React context
├── flag.tsx                  # Conditional component
└── flags-test-provider.tsx   # Testing utilities

⚡ Resolution Flow

1Define flags in defs/*.flag.ts files

2Wizard updates registry.config.ts automatically

3Server resolves all flags with context

4Client receives safe subset via provider

5Components use hooks or <Flag> wrapper

⚡ resolveAllFlags() Engine

The server-side engine that evaluates all your feature flags and returns their resolved values.

🔄 The Resolution Process

1Gets all flag keys from your registry

2Runs all flags in parallel for performance

3Calls each flag's decide() function with context

4Falls back to defaultValue if no decide function

5Validates results against Zod schemas

🎯 Usage Patterns

Basic Usage

await resolveAllFlags()

Simple flags using defaultValue

With Context

await resolveAllFlags({ getUser, getWorkspace })

Personalized flags with user data

In API Routes

const flags = await resolveAllFlags(ctx)

Server-side flag access

🔒 Security & Performance

Server-Only Execution

All decision logic runs securely on the server

Parallel Processing

All flags resolve simultaneously for speed

💻 Code Examples

1. Define a Flag

// lib/flags/defs/my-feature.flag.ts
import { z } from "zod";
import { defineFlag } from "../kit";

export const key = "my-awesome-feature" as const;
export const schema = z.boolean();

export default defineFlag({
  key,
  schema,
  description: "Enable my awesome new feature",
  defaultValue: false,
  client: { public: true },
  async decide(ctx) {
    const user = await ctx.getUser?.();
    return user?.plan === "premium";
  },
});

2. Use in Components

import { useFlag } from "@/components/flags/flags-provider";
import { Flag } from "@/components/flags/flag";

function MyComponent() {
  const isEnabled = useFlag("my-awesome-feature");
  
  return (
    <div>
      <h1>My App</h1>
      
      {/* Using the hook */}
      {isEnabled && <NewFeatureButton />}
      
      {/* Using the component */}
      <Flag when="my-awesome-feature">
        <NewFeaturePanel />
      </Flag>
    </div>
  );
}

3. Next.js App Router Integration

// app/layout.tsx (Server Component)
import { resolveAllFlags, pickClientFlags } from "@/lib/flags/runtime";
import { FlagsProvider } from "@/components/flags/flags-provider";

export default async function RootLayout({ children }) {
  // 🚀 resolveAllFlags() runs on the server and:
  // - Calls each flag's decide() function with context
  // - Validates results against Zod schemas  
  // - Returns ALL flags (including server-only ones)
  const serverFlags = await resolveAllFlags({
    getUser: async () => getCurrentUser(),
    getWorkspace: async () => getCurrentWorkspace(),
  });
  
  // 🔒 pickClientFlags() creates client-safe subset:
  // - Only includes flags with client: { public: true }
  // - Applies optional serialize() functions
  // - Excludes sensitive server-only flags
  const clientFlags = pickClientFlags(serverFlags);

  return (
    <html lang="en">
      <body>
        <FlagsProvider flags={clientFlags}>
          {children}
        </FlagsProvider>
      </body>
    </html>
  );
}

4. Testing with Overrides

import { FlagsTestProvider } from "@/components/flags/flags-test-provider";

function MyStory() {
  return (
    <FlagsTestProvider 
      overrides={{ "my-awesome-feature": true }}
    >
      <MyComponent />
    </FlagsTestProvider>
  );
}