feature flags - freeCodeCamp.org

How to Build a Production-Ready Feature Flag System with Next.js and Supabase

David Aniebo — Thu, 05 Feb 2026 22:40:14 +0000

Feature flags are powerful tools that let you control which features are visible to users without deploying new code. They enable gradual rollouts, A/B testing, and instant feature toggles, which are all essential for modern software development.

In this article, we’ll build a real, production-ready feature flag system, not just a simple boolean toggle.

Specifically, we’ll implement:

A global on/off flag to enable or disable features instantly
User-specific flags to grant access to individual users (for beta testing or internal users)
Percentage-based rollouts to gradually expose features to a subset of users
A React-powered admin dashboard to manage flags without redeploying
Client-side and server-side enforcement, so features are gated consistently everywhere

By the end, we’ll finish by wiring a real Todo feature behind a feature flag, showing how entire pages and components can be safely toggled on and off in production.

What Are Feature Flags?
Prerequisites
Project Setup
Database Schema Design
Setting Up Supabase
Building the Core Feature Flag Logic
Setting Up React Query
Creating the React Hook
Building the Admin Dashboard
Implementing a Real-World Example
Server-Side Usage
Why React Query?
Conclusion

Prerequisites

Before you begin, make sure you have:

Node.js 18 or higher installed
A basic understanding of React and Next.js
Familiarity with TypeScript
A Supabase account (free tier works perfectly)
A code editor like VS Code
Basic understanding of React Query (TanStack Query) for server state management

What Are Feature Flags?

Feature flags (also called feature toggles) are configuration mechanisms that let you enable or disable features in your application without changing code. Think of them as light switches for your features.

Here are some common use cases:

Gradual rollouts: Release a feature to 10% of users first, then gradually increase
User-specific access: Enable features for beta testers or VIP users
Emergency kill switches: Instantly disable a feature if something goes wrong
A/B testing: Test different versions of features with different user groups

Project Setup

Start by creating a new Next.js project with TypeScript:

npx create-next-app@latest supabase-feature-flag --typescript --tailwind --app
cd supabase-feature-flag

Next, install the required dependencies:

npm install @supabase/ssr @supabase/supabase-js @tanstack/react-query

The @supabase/ssr package provides server-side rendering support for Supabase, which is essential for Next.js App Router. @tanstack/react-query provides powerful server state management with automatic caching, invalidation, and real-time updates, which is perfect for feature flags that need to reflect changes immediately without page refreshes.

Database Schema Design

Before writing any code, you need to design your database schema. A feature flag needs several properties:

A unique key to identify the flag
A name and description for human readability
An enabled/disabled state
Support for user-specific access
Support for percentage-based rollouts

Here's the SQL migration that creates the feature_flags table:

-- Create feature_flags table
CREATE TABLE IF NOT EXISTS feature_flags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  enabled BOOLEAN DEFAULT false NOT NULL,
  enabled_for_users JSONB DEFAULT '[]'::jsonb,
  enabled_for_percent INTEGER DEFAULT 0 CHECK (enabled_for_percent >= 0 AND enabled_for_percent <= 100),
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);

Let's break down each field:

id: A unique identifier for each flag
key: A unique string identifier (like "new-dashboard" or "beta-feature")
name: A human-readable name
description: Optional description of what the flag controls
enabled: Global on/off switch
enabled_for_users: JSON array of user IDs who have access
enabled_for_percent: Percentage of users who should see the feature (0-100)
metadata: Flexible JSON field for additional configuration
created_at and updated_at: Timestamps for tracking

The migration also includes indexes for performance:

-- Create indexes for fast lookups
CREATE INDEX IF NOT EXISTS idx_feature_flags_key ON feature_flags(key);
CREATE INDEX IF NOT EXISTS idx_feature_flags_enabled ON feature_flags(enabled);

Indexes on key and enabled ensure fast queries when checking flag status.

Setting Up Supabase

Step 1: Create a Supabase Project

To start, go to supabase.com and sign up or log in. Then click on "New Project". Fill in your project details and wait for it to initialize.

Step 2: Run the Migration

In your Supabase dashboard, navigate to the SQL Editor:

Then click "New Query". Copy and paste the complete migration SQL (including the indexes and RLS policies shown below) and click "Run".

Here's the complete migration with Row Level Security (RLS) policies:

-- Create feature_flags table
CREATE TABLE IF NOT EXISTS feature_flags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  enabled BOOLEAN DEFAULT false NOT NULL,
  enabled_for_users JSONB DEFAULT '[]'::jsonb,
  enabled_for_percent INTEGER DEFAULT 0 CHECK (enabled_for_percent >= 0 AND enabled_for_percent <= 100),
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);

-- Create indexes
CREATE INDEX IF NOT EXISTS idx_feature_flags_key ON feature_flags(key);
CREATE INDEX IF NOT EXISTS idx_feature_flags_enabled ON feature_flags(enabled);

-- Auto-update updated_at timestamp
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ language 'plpgsql';

CREATE TRIGGER update_feature_flags_updated_at
  BEFORE UPDATE ON feature_flags
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at_column();

-- Enable Row Level Security
ALTER TABLE feature_flags ENABLE ROW LEVEL SECURITY;

-- Policy: Allow public read access
CREATE POLICY "Allow public read access"
  ON feature_flags
  FOR SELECT
  USING (true);

-- Policy: Allow public write access (for admin operations)
CREATE POLICY "Allow public write access"
  ON feature_flags
  FOR ALL
  USING (true)
  WITH CHECK (true);

The RLS policies allow:

Public read access: Anyone can check if a feature flag is enabled
Public write access: Allows the admin dashboard to create/update flags (in production, you'd restrict this further)

Step 3: Get Your API Credentials

Go to Settings and then API in your Supabase project. Copy your Project URL and Publishable Key. THen create a .env.local file in your project root:

NEXT_PUBLIC_SUPABASE_URL=your_project_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your_publishable_key

Building the Core Feature Flag Logic

Now let's build the core logic for checking feature flags. You'll create separate utilities for client-side and server-side usage.

TypeScript Types

First, define the types you'll use throughout the application:

// types/feature-flag.ts
export interface FeatureFlag {
  id: string;
  key: string;
  name: string;
  description: string | null;
  enabled: boolean;
  enabled_for_users: string[];
  enabled_for_percent: number;
  metadata: Record<string, any>;
  created_at: string;
  updated_at: string;
}

export interface FeatureFlagCheckResult {
  enabled: boolean;
  reason?: string;
}

The FeatureFlag interface matches your database schema. The FeatureFlagCheckResult includes a reason field that explains why a flag is enabled or disabled, which is useful for debugging.

Supabase Client Setup

Create the Supabase client for client-side usage:

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY;

export const createClient = () =>
  createBrowserClient(supabaseUrl!, supabaseKey!);

The createBrowserClient function from @supabase/ssr creates a client optimized for browser usage.

For server-side usage:

// lib/supabase/server.ts
import { createServerClient, type CookieOptions } from "@supabase/ssr";
import { cookies } from "next/headers";

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY;

export const createClient = (cookieStore: ReturnType<typeof cookies>) => {
  return createServerClient(
    supabaseUrl!,
    supabaseKey!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {
            // The `setAll` method was called from a Server Component.
            // This can be ignored if you have middleware refreshing
            // user sessions.
          }
        },
      },
    },
  );
};

This server client handles cookies properly for Next.js server components and API routes.

Client-Side Feature Flag Logic

Create the client-side utility for checking feature flags:

// lib/feature-flags/client.ts
import { createClient } from '@/lib/supabase/client';
import { FeatureFlag, FeatureFlagCheckResult } from '@/types/feature-flag';

// Simple cache with 5 second TTL (React Query handles primary caching)
// This cache is just for reducing redundant calls within a very short window
const cache = new Map<string, { data: FeatureFlag | null; expires: number }>();
const CACHE_TTL = 5000; // 5 seconds - short enough to not interfere with React Query invalidation

function getCached(key: string): FeatureFlag | null | undefined {
  const cached = cache.get(key);
  if (cached && cached.expires > Date.now()) {
    return cached.data;
  }
  return undefined;
}

function setCached(key: string, data: FeatureFlag | null): void {
  cache.set(key, { data, expires: Date.now() + CACHE_TTL });
}

The cache reduces database queries by storing flag data in memory for 5 seconds. This is a secondary cache layer – React Query handles the primary caching and automatic invalidation, ensuring changes reflect immediately across all components.

The getFeatureFlag function fetches a flag from the database:

export async function getFeatureFlag(key: string): Promise<FeatureFlag | null> {
  const cached = getCached(key);
  if (cached !== undefined) return cached;

  const supabase = createClient();
  const { data, error } = await supabase
    .from('feature_flags')
    .select('*')
    .eq('key', key)
    .single();

  if (error) {
    if (error.code === 'PGRST116') {
      setCached(key, null);
      return null;
    }
    console.error('Error fetching feature flag:', error);
    return null;
  }

  setCached(key, data);
  return data;
}

The function first checks the cache. If the flag isn't cached, it queries Supabase. The error code PGRST116 means "not found." In that case, you cache null to avoid repeated queries for non-existent flags.

The core logic is in isFeatureEnabled:

export async function isFeatureEnabled(
  key: string,
  userId?: string
): Promise<FeatureFlagCheckResult> {
  const flag = await getFeatureFlag(key);

  if (!flag) {
    return { enabled: false, reason: 'Flag not found' };
  }

  if (!flag.enabled) {
    return { enabled: false, reason: 'Flag is globally disabled' };
  }

  // Check user-specific access
  if (userId && flag.enabled_for_users.length > 0) {
    if (flag.enabled_for_users.includes(userId)) {
      return { enabled: true, reason: 'User has explicit access' };
    }
    return { enabled: false, reason: 'User not in allowed list' };
  }

  // Check percentage rollout
  if (flag.enabled_for_percent > 0) {
    const hash = simpleHash(userId || key);
    const percentage = hash % 100;
    const enabled = percentage < flag.enabled_for_percent;

    return {
      enabled,
      reason: enabled
        ? `User falls within ${flag.enabled_for_percent}% rollout`
        : `User falls outside ${flag.enabled_for_percent}% rollout`,
    };
  }

  return { enabled: true, reason: 'Flag is globally enabled' };
}

The function follows this logic:

Flag doesn't exist: Return disabled
Flag is globally disabled: Return disabled
User-specific list exists: Check if the user is in the list
Percentage rollout is set: Use a hash function to assign users to buckets deterministically
Otherwise: Flag is globally enabled

The hash function ensures consistent assignment, so that the same user always gets the same result:

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = (hash << 5) - hash + char;
    hash = hash & hash;
  }
  return Math.abs(hash);
}

This creates a deterministic hash, so simpleHash("user-123") always returns the same number, ensuring consistent feature flag decisions.

Server-Side Feature Flag Logic

The server-side version is similar but uses the server Supabase client:

// lib/feature-flags/server.ts
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';
import { FeatureFlag, FeatureFlagCheckResult } from '@/types/feature-flag';

export async function getFeatureFlag(key: string): Promise<FeatureFlag | null> {
  const cookieStore = await cookies();
  const supabase = createClient(cookieStore);

  const { data, error } = await supabase
    .from('feature_flags')
    .select('*')
    .eq('key', key)
    .single();

  if (error) {
    if (error.code === 'PGRST116') return null;
    console.error('Error fetching feature flag:', error);
    return null;
  }

  return data;
}

export async function isFeatureEnabled(
  key: string,
  userId?: string
): Promise<FeatureFlagCheckResult> {
  const flag = await getFeatureFlag(key);

  if (!flag) {
    return { enabled: false, reason: 'Flag not found' };
  }

  if (!flag.enabled) {
    return { enabled: false, reason: 'Flag is globally disabled' };
  }

  // Check user-specific access
  if (userId && flag.enabled_for_users.length > 0) {
    if (flag.enabled_for_users.includes(userId)) {
      return { enabled: true, reason: 'User has explicit access' };
    }
    return { enabled: false, reason: 'User not in allowed list' };
  }

  // Check percentage rollout
  if (flag.enabled_for_percent > 0) {
    const hash = simpleHash(userId || key);
    const percentage = hash % 100;
    const enabled = percentage < flag.enabled_for_percent;

    return {
      enabled,
      reason: enabled
        ? `User falls within ${flag.enabled_for_percent}% rollout`
        : `User falls outside ${flag.enabled_for_percent}% rollout`,
    };
  }

  return { enabled: true, reason: 'Flag is globally enabled' };
}

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = (hash << 5) - hash + char;
    hash = hash & hash;
  }
  return Math.abs(hash);
}

The logic is identical to the client version, but it uses the server Supabase client that handles cookies correctly.

Setting Up React Query

We’ll rely heavily on React Query throughout this tutorial because feature flags are server-driven values that can change at runtime while users are actively using the application.

React Query provides robust server-state management through caching, background refetching, and cache invalidation. This allows feature flag changes to propagate automatically across the app without forcing page refreshes or manual state synchronization.

Create the Query Provider

First, create the providers/QueryProvider.tsx file to configure and initialize React Query for the entire application:

'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';

export function QueryProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            // With SSR, we usually want to set some default staleTime
            // above 0 to avoid refetching immediately on the client
            staleTime: 20 * 1000,
            refetchOnWindowFocus: true,
            refetchOnReconnect: true,
          },
        },
      })
  );

  return (
    {children}
  );
}

What’s happening in this code:

This file runs on the client because React Query relies on React hooks, which only execute in the browser.
A single QueryClient instance is created and stored in state so it persists across renders and isn’t recreated.
The QueryClient defines how server data is cached, when it becomes stale, and when it should be refetched.

This is important because components no longer need to handle fetch logic, loading states, or caching manually. Also, server data is shared and reused across components instead of being refetched repeatedly. And feature flag updates propagate automatically, keeping the app consistent without manual refreshes.

Add Provider to Root Layout

Next, update the app/layout.tsx file to wrap the application with the React Query provider.

import type { Metadata } from 'next'
import './globals.css'
import { QueryProvider } from '@/providers/QueryProvider'

export const metadata: Metadata = {
  title: 'Feature Flag System',
  description: 'Production-ready feature flag system with Next.js and Supabase',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    "en">
      
        {children}
      
    
  )
}

We wrap the entire application with QueryProvider, so React Query can manage server data globally across the app.

What `QueryProvider` actually does

QueryProvider creates and shares a single Query Client that is responsible for:

Caching data fetched from the server
Tracking loading and error states
Automatically refetching data when needed
Synchronizing data between components

By wrapping the app, every component inside it can use React Query hooks without any extra setup.

Creating the React Hook

Create the hooks/useFeatureFlag.ts file to check whether a feature flag is enabled for a user, using React Query to cache and share the data across components:

'use client';

import { useQuery } from '@tanstack/react-query';
import { isFeatureEnabled } from '@/lib/feature-flags/client';
import { FeatureFlagCheckResult } from '@/types/feature-flag';

export function useFeatureFlag(key: string, userId?: string) {
  const {
    data: result = { enabled: false, reason: 'Loading...' },
    isLoading: loading,
    error,
  } = useQuery({
    queryKey: ['featureFlag', key, userId],
    queryFn: () => isFeatureEnabled(key, userId),
    staleTime: 30 * 1000,
    refetchOnWindowFocus: true,
  });

  return { ...result, loading, error };
}

What’s happening in the code:

'use client'; ensures this file runs in the browser because React Query hooks can only run on the client.
useQuery fetches the feature flag status from the server and caches the result.
queryKey: ['featureFlag', key, userId] uniquely identifies this query so React Query can cache it separately for each feature and user.
queryFn: () => isFeatureEnabled(key, userId) is the function that actually checks if the feature is enabled.
staleTime: 30 * 1000 keeps the cached data fresh for 30 seconds before refetching.
refetchOnWindowFocus: true automatically refetches the data when the user switches back to the tab.
return { ...result, loading, error } makes it easy for components to access the flag status, loading state, and any errors.

Admin Hooks for Managing Flags

We’re going to create a set of React Query hooks to manage feature flags from the admin dashboard. These hooks allow you to fetch, create, update, and delete feature flags while automatically keeping your UI in sync.

Step 1: Create the hooks file

Start by creating a new file at hooks/useFeatureFlags.ts file. This is where we’ll implement all the hooks for the admin to manage feature flags.

After creating the hooks/useFeatureFlags.ts file, import React Query hooks and the FeatureFlag type so we can fetch, update, create, and delete feature flags with type safety and caching.

'use client';

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { FeatureFlag } from '@/types/feature-flag';

In this code:

useQuery fetches and caches server data automatically.
useMutation sends updates, creates, or deletes data on the server.
useQueryClient gives access to the query cache so we can invalidate or update queries after mutations.
FeatureFlag is the TypeScript type definition for feature flags, ensuring our hooks use correct data structures.

Step 2: Add a hook to fetch all feature flags

Next, in the same hooks/useFeatureFlags.ts file, add a hook to fetch all feature flags for the admin page. This hook will allow components to retrieve the list of flags and automatically cache the data using React Query.

export function useFeatureFlags() {
  return useQuery({
    queryKey: ['featureFlags'],
    queryFn: async () => {
      const response = await fetch('/api/feature-flags');
      const { data } = await response.json();
      return data || [];
    },
    staleTime: 30 * 1000,
  });
}

What’s happening in the code:

useQuery fetches all feature flags from the server and caches them automatically.
queryKey: ['featureFlags'] uniquely identifies this query so React Query can manage caching and refetching.
queryFn is an async function that calls the /api/feature-flags endpoint and returns the data.
staleTime: 30 * 1000 keeps the cached data fresh for 30 seconds before refetching.

This matters because admin components always display the latest flags without manual refresh. Also, cached data reduces unnecessary network requests. Finally, any component using this hook will automatically update when the flags change.

Step 3: Add a hook to update a feature flag

Next, in the same hooks/useFeatureFlags.ts file, add a hook to update an existing feature flag. This hook will allow the admin to modify a flag and ensure all components using it get the updated value automatically.

export function useUpdateFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async ({
      key,
      updates,
    }: {
      key: string;
      updates: Partial;
    }) => {
      const response = await fetch(`/api/feature-flags/${key}`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updates),
      });

      if (!response.ok) {
        throw new Error('Failed to update feature flag');
      }

      const { data } = await response.json();
      return data;
    },
    onSuccess: (data, variables) => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
      // Invalidate the specific feature flag check
      queryClient.invalidateQueries({
        queryKey: ['featureFlag', variables.key],
      });
      // Invalidate all feature flag checks (in case userId was involved)
      queryClient.invalidateQueries({ queryKey: ['featureFlag'] });
    },
  });
}

What’s happening in the code:

useMutation creates a function to update a feature flag on the server.
mutationFn is an async function that sends a PATCH request to /api/feature-flags/${key} with the updated data.
onSuccess runs after a successful update to invalidate cached queries so the latest data is available everywhere:
- ['featureFlags'] updates the full list of flags.
- ['featureFlag', variables.key] updates the specific flag that was changed.
- ['featureFlag'] updates any other cached flag checks (for example, per user checks).

Step 4: Add a hook to delete a feature flag

Next, add the useDeleteFeatureFlag hook to delete a feature flag. This hook allows the admin to remove a flag from the system and ensures the UI updates automatically everywhere the flag was used.

export function useDeleteFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (key: string) => {
      const response = await fetch(`/api/feature-flags/${key}`, {
        method: 'DELETE',
      });

      if (!response.ok) {
        throw new Error('Failed to delete feature flag');
      }
    },
    onSuccess: (_, key) => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
      // Invalidate the specific feature flag check
      queryClient.invalidateQueries({ queryKey: ['featureFlag', key] });
    },
  });
}

What’s happening in the code:

useMutation creates a function to delete a feature flag from the server.
mutationFn is an async function that sends a DELETE request to /api/feature-flags/${key}.
onSuccess runs after the flag is successfully deleted to invalidate the cache so the UI updates:
- ['featureFlags'] refetches the full list of flags.
- ['featureFlag', key] removes the deleted flag from any cached queries.

Step 5: Add a hook to create a new feature flag

Finally, add the useCreateFeatureFlag hook to create a new feature flag. This allows the admin to add new flags and ensures the dashboard updates automatically when a new flag is created.

export function useCreateFeatureFlag() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (flag: {
      key: string;
      name: string;
      description?: string;
      enabled?: boolean;
      enabled_for_users?: string[];
      enabled_for_percent?: number;
      metadata?: Record<string, any>;
    }) => {
      const response = await fetch('/api/feature-flags', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(flag),
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error || 'Failed to create feature flag');
      }

      const { data } = await response.json();
      return data;
    },
    onSuccess: () => {
      // Invalidate and refetch feature flags list
      queryClient.invalidateQueries({ queryKey: ['featureFlags'] });
    },
  });
}

What’s happening in the code:

useMutation creates a function to send a new feature flag to the server.
mutationFn is an async function that posts the flag data to /api/feature-flags.
onSuccess runs after a successful creation to invalidate the cached list of flags, so the admin dashboard shows the new flag immediately.

Feature Flag Gate Component

Now we’ll create a wrapper component to conditionally render UI based on feature flags. This helps you show or hide parts of your app depending on whether a flag is enabled for a user.

Create the components/FeatureFlagGate.tsx file and add the following code:

'use client';

import { ReactNode } from 'react';
import { useFeatureFlag } from '@/hooks/useFeatureFlag';

interface FeatureFlagGateProps {
  flagKey: string;
  userId?: string;
  children: ReactNode;
  fallback?: ReactNode;
  showLoading?: ReactNode;
}

export function FeatureFlagGate({
  flagKey,
  userId,
  children,
  fallback = null,
  showLoading = null,
}: FeatureFlagGateProps) {
  const { enabled, loading } = useFeatureFlag(flagKey, userId);

  if (loading && showLoading !== null) {
    return <>{showLoading};
  }

  if (!enabled) {
    return <>{fallback};
  }

  return <>{children};
}

What’s happening in the code:

useFeatureFlag(flagKey, userId) checks whether the feature is enabled for a specific user and tracks loading state.
loading && showLoading !== null: if the data is still loading, render the optional showLoading UI.
!enabled: if the feature is disabled, render the optional fallback UI.
children renders the actual content only if the flag is enabled and not loading.

This makes it easy to conditionally render features without scattering logic throughout your components. It also supports custom loading and fallback UI for better user experience. And it works with React Query caching automatically, so flag changes propagate immediately.

Building the Admin Dashboard

Admins need a way to manage feature flags in your app. To do this, we’ll create API routes that support CRUD operations (Create, Read, Update, Delete). These routes will interact with Supabase to store and modify flag data.

Step 1: Create the main feature flags API route

Start by creating the app/api/feature-flags/route.ts file. This file will handle fetching all feature flags (GET) and creating new ones (POST).

import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';

export async function GET(request: NextRequest) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const { data, error } = await supabase
      .from('feature_flags')
      .select('*')
      .order('created_at', { ascending: false });

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

export async function POST(request: NextRequest) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const body = await request.json();

    if (!body.key || !body.name) {
      return NextResponse.json(
        { error: 'key and name are required' },
        { status: 400 }
      );
    }

    const { data, error } = await supabase
      .from('feature_flags')
      .insert({
        key: body.key,
        name: body.name,
        description: body.description || null,
        enabled: body.enabled || false,
        enabled_for_users: body.enabled_for_users || [],
        enabled_for_percent: body.enabled_for_percent || 0,
        metadata: body.metadata || {},
      })
      .select()
      .single();

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data }, { status: 201 });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

What’s happening in this file:

GET fetches all feature flags from Supabase, ordered by creation date.
POST creates a new feature flag in Supabase. It checks that key and name exist, and sets defaults for optional fields.
createClient(cookieStore) authenticates requests with Supabase using cookies from the client.
NextResponse.json() sends JSON responses with data or error messages.

Step 2: Create the dynamic route for individual flags

Next, Create the file app/api/feature-flags/[key]/route.ts. This route handles updating (PATCH) and deleting (DELETE) individual flags based on their key.

import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { cookies } from 'next/headers';

export async function PATCH(
  request: NextRequest,
  { params }: { params: { key: string } }
) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);
    const body = await request.json();

    const { data, error } = await supabase
      .from('feature_flags')
      .update({
        ...(body.name !== undefined && { name: body.name }),
        ...(body.description !== undefined && { description: body.description }),
        ...(body.enabled !== undefined && { enabled: body.enabled }),
        ...(body.enabled_for_users !== undefined && {
          enabled_for_users: body.enabled_for_users,
        }),
        ...(body.enabled_for_percent !== undefined && {
          enabled_for_percent: body.enabled_for_percent,
        }),
      })
      .eq('key', params.key)
      .select()
      .single();

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ data });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

export async function DELETE(
  request: NextRequest,
  { params }: { params: { key: string } }
) {
  try {
    const cookieStore = await cookies();
    const supabase = createClient(cookieStore);

    const { error } = await supabase
      .from('feature_flags')
      .delete()
      .eq('key', params.key);

    if (error) {
      return NextResponse.json({ error: error.message }, { status: 500 });
    }

    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

What’s happening in this file:

PATCH updates a feature flag with only the fields provided in the request body.
- Uses the spread operator (...) to include only fields that exist.
DELETE removes the feature flag identified by key.
eq('key', params.key) ensures the operation targets the correct flag.

Step 3: Create the Admin Dashboard UI

Now, create the file app/admin/page.tsx. This is the main admin dashboard where you can view, create, and manage feature flags.

With React Query, the admin dashboard becomes much cleaner and automatically updates when flags change:

'use client';

import { useState } from 'react';
import { FeatureFlagList } from '@/components/admin/FeatureFlagList';
import { CreateFeatureFlagModal } from '@/components/admin/CreateFeatureFlagModal';
import { useFeatureFlags } from '@/hooks/useFeatureFlags';

export default function AdminPage() {
  const [showCreateModal, setShowCreateModal] = useState(false);
  const { data: flags = [], isLoading: loading } = useFeatureFlags();

  return (
    'min-h-screen bg-gray-50 py-8'>
      'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8'>
        'mb-8 flex justify-between items-center'>
          
            'text-3xl font-bold text-gray-900'>
              Feature Flags Admin
            
            'mt-2 text-sm text-gray-600'>
              Manage your feature flags and rollouts
            
          
          
        

        {loading ? (
          'text-center py-12'>
            'inline-block animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600'>
            'mt-4 text-gray-600'>Loading feature flags...
          
        ) : (
          
        )}

        {showCreateModal && (
          () => setShowCreateModal(false)}
            onSuccess={() => {
              setShowCreateModal(false);
            }}
          />
        )}
      
    
  );
}

What’s happening in this file:

'use client'; marks this page as a client component so hooks like useState and React Query can run.
useState manages whether the “Create Feature Flag” modal is open or closed.
useFeatureFlags() fetches all feature flags from the API and keeps the list in sync automatically.
const { data: flags = [], isLoading: loading } :
- flags contains the feature flag list
- loading tracks whether the data is still being fetched
loading ? ... : :
- Shows a loading spinner while flags are being fetched
- Renders the feature flag table once data is available
FeatureFlagList displays all feature flags and their current states.

Using Feature Flags Mutations in Components

Earlier, we created mutation hooks for creating, updating, and deleting feature flags. Now let’s see how those hooks are actually used inside UI components to trigger updates and keep the interface in sync.

Here's how to use the mutation hooks in your components:

'use client'

import { useState } from 'react'
import { FeatureFlag } from '@/types/feature-flag'
import { EditFeatureFlagModal } from './EditFeatureFlagModal'
import {
  useUpdateFeatureFlag,
  useDeleteFeatureFlag,
} from '@/hooks/useFeatureFlags'

interface FeatureFlagCardProps {
  flag: FeatureFlag
}

export function FeatureFlagCard({ flag }: FeatureFlagCardProps) {
  const [isEditing, setIsEditing] = useState(false)
  const updateFlag = useUpdateFeatureFlag()
  const deleteFlag = useDeleteFeatureFlag()

  const handleToggle = async () => {
    try {
      await updateFlag.mutateAsync({
        key: flag.key,
        updates: { enabled: !flag.enabled },
      })
    } catch (error) {
      console.error('Error toggling flag:', error)
      alert('Failed to toggle feature flag')
    }
  }

  const handleDelete = async () => {
    if (!confirm(`Are you sure you want to delete "${flag.name}"?`)) {
      return
    }

    try {
      await deleteFlag.mutateAsync(flag.key)
    } catch (error) {
      console.error('Error deleting flag:', error)
      alert('Failed to delete feature flag')
    }
  }

  return (
    <>
      "bg-white rounded-lg shadow p-6">
        "flex items-start justify-between">
          "flex-1">
            "flex items-center gap-3">
              "text-lg font-semibold text-gray-900">
                {flag.name}
              
              `px-2 py-1 text-xs font-medium rounded-full ${
                  flag.enabled
                    ? 'bg-green-100 text-green-800'
                    : 'bg-gray-100 text-gray-800'
                }`}
              >
                {flag.enabled ? 'Enabled' : 'Disabled'}
              
            
            "mt-1 text-sm text-gray-600 font-mono">{flag.key}
            {flag.description && (
              "mt-2 text-sm text-gray-500">{flag.description}
            )}

            "mt-4 flex flex-wrap gap-4 text-sm text-gray-600">
              {flag.enabled_for_users.length > 0 && (
                
                  "font-medium">Users:{' '}
                  {flag.enabled_for_users.length} user(s)
                
              )}
              {flag.enabled_for_percent > 0 && (
                
                  "font-medium">Rollout:{' '}
                  {flag.enabled_for_percent}%
                
              )}
            
          

          "flex items-center gap-2 ml-4">
            
            
            
          
        
      

      {isEditing && (
        () => setIsEditing(false)}
          onSuccess={() => {
            setIsEditing(false)
          }}
        />
      )}
    
  )
}

The component above works without any manual refetching or state synchronization logic. The moment a mutation succeeds, React Query automatically updates or invalidates the relevant cached data. That behavior is what enables the smooth, real-time updates you see in the UI.

Because all feature flag data is managed by React Query:

When a flag is toggled, React Query automatically invalidates the relevant queries
Any component using that flag immediately receives the updated value
The admin dashboard stays in sync with the rest of the application without extra code
Loading and error states are handled consistently across all mutations.

Implementing a Real-World Example

To make all of this concrete, let’s walk through a real-world example.

In this section, we’ll build a simple Todo feature that is entirely controlled by a feature flag. When the flag is disabled, users see a message explaining that the feature isn’t available. When it’s enabled, the full Todo interface appears instantly without redeploying or refreshing the page.

This demonstrates how feature flags can safely gate entire pages or features in a live application.

Below is what the experience looks like as the feature flag is toggled on and off from the admin dashboard:

Step 1: Create the Todo Page File

Create a new file app/todos/page.tsx. This page shows how to use a feature flag to conditionally render a full component. Let's build a todo app that's controlled by a feature flag. This demonstrates real-world usage.

At the top of the file, import the hooks we need and define the Todo interface.

'use client';

import { useState, useEffect } from 'react';
import { FeatureFlagGate } from '@/components/FeatureFlagGate';

interface Todo {
  id: string;
  text: string;
  completed: boolean;
}

Step 2: Initialize state in the component

Create the component and define state for todos and the input:

export default function TodosPage() {
  const [todos, setTodos] = useState([]);
  const [inputValue, setInputValue] = useState('');

Here’s what’s going on:

todos stores all todo items.
inputValue tracks what the user types in the input field.

Step 3: Load and save todos from localStorage

  useEffect(() => {
    const saved = localStorage.getItem('todos');
    if (saved) setTodos(JSON.parse(saved));
  }, []);

  useEffect(() => {
    localStorage.setItem('todos', JSON.stringify(todos));
  }, [todos]);

In this code, the first useEffect loads saved todos from the browser’s localStorage when the component mounts. The second useEffect saves todos whenever the list changes. This ensures your todos persist across page reloads.

Step 4: Add helper functions

  const addTodo = () => {
    if (inputValue.trim()) {
      setTodos([...todos, { 
        id: Date.now().toString(), 
        text: inputValue.trim(), 
        completed: false 
      }]);
      setInputValue('');
    }
  };

  const toggleTodo = (id: string) => {
    setTodos(todos.map(todo => 
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    ));
  };

  const deleteTodo = (id: string) => {
    setTodos(todos.filter(todo => todo.id !== id));
  };

In this code,

addTodo adds a new todo item with a unique id and resets the input.
toggleTodo marks a todo as completed or incomplete.
deleteTodo removes a todo from the list.

Step 5: Render the Todo App inside the FeatureFlagGate

  return (
    <div className="max-w-2xl mx-auto p-8">
      <h1 className="text-4xl font-bold mb-6">Todo Apph1>

      <FeatureFlagGate
        flagKey="test"
        fallback={
          <div className="bg-yellow-50 border-2 border-yellow-200 rounded-lg p-6">
            <h3 className="font-semibold mb-2">Feature Not Availableh3>
            <p>Enable the "test" feature flag in the admin dashboard.p>
          div>
        }
      >

What’s going on here:

We wrap the Todo app in FeatureFlagGate.
flagKey="test" only shows the Todo app if this feature flag is enabled.
fallback displays a message when the feature is disabled.

Step 6: Add the input field and Add button

        <div className="mb-6">
          <div className="flex gap-2">
            <input
              type="text"
              value={inputValue}
              onChange={(e) => setInputValue(e.target.value)}
              onKeyPress={(e) => e.key === 'Enter' && addTodo()}
              placeholder="What needs to be done?"
              className="flex-1 px-4 py-3 border rounded-lg"
            />
            <button
              onClick={addTodo}
              className="px-6 py-3 bg-purple-600 text-white rounded-lg"
            >
              Add
            button>
          div>
        div>

In this code,

Input field captures new todo text.
Pressing Enter or clicking Add triggers addTodo.
It’s styled with Tailwind CSS for spacing and rounded borders.

Step 8: Display the list of todos


        <div className="space-y-2">
          {todos.map((todo) => (
            <div
              key={todo.id}
              className="flex items-center gap-3 p-4 bg-gray-50 rounded-lg"
            >
              <button
                onClick={() => toggleTodo(todo.id)}
                className={`w-6 h-6 rounded-full border-2 ${
                  todo.completed
                    ? 'bg-green-500 border-green-500'
                    : 'border-gray-300'
                }`}
              >
                {todo.completed && '✓'}
              button>
              <span className={todo.completed ? 'line-through' : ''}>
                {todo.text}
              span>
              <button
                onClick={() => deleteTodo(todo.id)}
                className="text-red-500"
              >
                Delete
              button>
            div>
          ))}
        div>
      FeatureFlagGate>
    div>
  );
}

This code,

Loops over todos to display each item.
Shows a toggle button to mark as complete, a delete button, and the todo text.
Completed todos get a line-through style.
All interaction happens inside the FeatureFlagGate, so users only see this when the flag is enabled.
The entire todo app is wrapped in FeatureFlagGate. When the "test" flag is disabled, users see a message instead of the app. When enabled, they see the full todo interface.

Todo App Overview

This Todo app demonstrates how feature flags work in a live application. It shows how admins can enable or disable the "test" feature flag dynamically from the dashboard.

FeatureFlagGate ensures the interface updates immediately when the flag changes, and entire components or pages can be toggled on or off safely using feature flags.

Server-Side Usage

Feature flags shouldn’t only live on the client. In many cases, you’ll want to enforce them on the server as well, especially for APIs, background jobs, or sensitive business logic.

In this example, we’ll protect an API route by checking a feature flag on the server before returning any data.

First, create the API route file app/api/some-feature/route.ts. This demonstrates how to check a feature flag on the server before returning data.

import { isFeatureEnabled } from '@/lib/feature-flags/server';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const userId = request.headers.get('user-id') || undefined;
  const result = await isFeatureEnabled('new-feature', userId);

  if (!result.enabled) {
    return NextResponse.json(
      { error: 'Feature not available' },
      { status: 403 }
    );
  }

  // Feature is enabled, proceed with logic
  return NextResponse.json({ data: 'Feature content' });
}

What’s happening in this file:

File creation: app/api/some-feature/route.ts defines a new API route.
isFeatureEnabled: Checks whether the 'new-feature' flag is active for the user.
Conditional response: Returns a 403 error if the feature is disabled. Otherwise, proceeds normally.
Server-side gating: Lets you protect entire endpoints, so users only access functionality when the feature is enabled.

Why React Query?

Feature flags introduce a unique challenge because they must remain consistent across the entire UI even as they change dynamically. Without a dedicated server-state solution, you’d need to manually refetch data, coordinate updates between components, and handle edge cases where parts of the UI fall out of sync.

React Query treats feature flags as shared server state. Once fetched, flags are cached and reused across components. When an admin updates a flag, the cache is invalidated and refetched in the background, triggering immediate UI updates everywhere the flag is used. This makes React Query a natural fit for feature flags, where correctness, consistency, and real-time updates are critical.

Real-World Impact

Before React Query:

// Had to manually refetch after every update
const handleToggle = async () => {
  await fetch(`/api/feature-flags/${key}`, { method: 'PATCH', ... });
  fetchFlags(); // Manual refetch
  // Other components still show old data until page refresh
};

After React Query:

// Automatic cache invalidation - everything updates instantly
const updateFlag = useUpdateFeatureFlag();
await updateFlag.mutateAsync({ key, updates });
// All components using this flag automatically update!

Conclusion

You’ve now built a complete, production-ready feature flag system using Next.js and Supabase. The system supports global toggles, user-specific access, and percentage-based rollouts, all backed by a flexible database schema.

Feature flags can be checked on both the client and the server, ensuring consistent behavior across UI components and API routes. With React Query handling caching and invalidation, changes made in the admin dashboard propagate instantly throughout the application without deploying or refreshing the page.

Feature flags are a foundational tool for modern development. They let you deploy code safely, test new ideas with real users, and react quickly when something goes wrong. With this setup in place, you can confidently extend the system with audit logs, analytics, scheduled rollouts, or deeper CI/CD integrations as your product grows.

How to Build a Flexible API with Feature Flags Using Open Source Tools

Pradumna Saraf — Tue, 19 Nov 2024 22:56:26 +0000

Feature flagging has changed the paradigm of how backend developers can test and modify the things they build. With feature flags, we can enable and disable a feature or change the functionality of something on the fly with a single click (no need to redeploy).

In this tutorial, we will see how feature flags help us to enable and disable a feature/a part of code whenever we want from the UI, without the need to redeploy the whole code.

To understand things more deeply, we will build an app from scratch, look at feature flagging capabilities, and use a tool called Flagsmith to manage our created feature flags from a single dashboard.

Prerequisites

Golang installed and a medium-level understanding of it.
A running Redis instance (Remote or local instance)
Flagsmith Account (It’s Free. We will cover this later in the article.)

What is a Feature Flag?

Feature Flag is a technique in development that allows teams to turn features on or off without modifying the source code or redeploying.

To make it a bit simpler, think of them as functioning sort of like conditional statements (for example, if-else statements): based on when something’s true or false, it determines the code path that will be executed.

Feature Flags for Backend Development

You may have seen feature flags used in frontends and websites, but there is much more to them. You can use them on the server side to modify the functionality of an API, doing things like modifying/setting the rate limit, changing the API endpoint's functionality or completely turning it off. As backend developers, we can level up our testing with feature flags.

To demonstrate this, we will go through building a demo app. The demo app is curated to show feature flagging capabilities from modifying the functionality (rate limit) on the fly to adding a new endpoint to the API for beta testing or initial rolling purposes. We’ll use entirely open-source tools along the way!

Why Use Open Source Tools?

We will be using open source tools to build this app (Golang, Redis, and Flagsmith). Open source brings more transparency and trust and encourages collaboration with the global community of backend developers.

By integrating open source tools, we get full visibility as we build and test. For example, we will integrate feature flags with GitHub, which lets us track the lifecycle of a feature by linking a Flagsmith feature flag with a GitHub Pull Request or Issue. This lets us stay updated with the changes to our features without having to manually track each modification. We can easily track the status of our features across different environments.

Let’s Code!

In this tutorial, you’ll see how the functionality of an app changes before and after testing with feature flagging mechanisms. The tools and frameworks we’ll use are Golang, Docker, Redis, Flagsmith, and GitHub. As discussed, all are open source and free to create an account to test.

To get started, open your favourite IDE, initialize a Golang project, and then copy the below code in the main.go file. Then run go mod tidy to install all the dependencies it needs.

Let’s understand what’s going on in the below code snippet:

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "net/http"
    "os"
    "strconv"

    "github.com/gin-gonic/gin"
    "github.com/go-redis/redis_rate/v10"
    "github.com/joho/godotenv"
    "github.com/redis/go-redis/v9"
)

var (
    redisClient *redis.Client
    limiter     *redis_rate.Limiter
)

func initClients() {
    redisClient = redis.NewClient(&redis.Options{
        Addr: os.Getenv("REDIS_URL"),
    })
    limiter = redis_rate.NewLimiter(redisClient)
}

func main() {
    err := godotenv.Load()
    if err != nil {
        log.Printf("Loading environment variable from the host system")
    } else {
        log.Printf("Loading environment from .env file")
    }

    initClients()
    defer redisClient.Close()

    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        err, remainingLimit := rateLimitCall(c.ClientIP())
        if err != nil {
            c.JSON(
                http.StatusTooManyRequests,
                gin.H{"error": "Rate Limit Hit"})
        } else {
            c.JSON(
                http.StatusOK,
                gin.H{"Your left over API request is": remainingLimit})
        }
    })
    r.GET("/beta", func(c *gin.Context) {
        c.JSON(
            http.StatusOK,
            gin.H{"message": "This is beta endpoint"})
    })
    r.Run(":" + os.Getenv("PORT"))
}

func rateLimitCall(ClientIP string) (error, int) {
    ctx := context.Background()

    rateLimitString := os.Getenv("RATE_LIMIT")
    RATE_LIMIT, _ := strconv.Atoi(rateLimitString)

    res, err := limiter.Allow(ctx, ClientIP, redis_rate.PerHour(RATE_LIMIT))
    if err != nil {
        panic(err)
    }

    if res.Remaining == 0 {
        return errors.New("You have hit the Rate Limit for the API. Try again later"), 0
    }

    fmt.Println("remaining request for", ClientIP, "is", res.Remaining)
    return nil, res.Remaining
}

Initializing the Tools

func initClients() {
    redisClient = redis.NewClient(&redis.Options{
        Addr: os.Getenv("REDIS_URL"),
    })
    limiter = redis_rate.NewLimiter(redisClient)
}

func main() {
    err := godotenv.Load()
    if err != nil {
        log.Printf("Loading environment variable from the host system")
    } else {
        log.Printf("Loading environment from .env file")
    }

    initClients()
    defer redisClient.Close()

    r := gin.Default()
    ...
    })

At the top, we declare variables to store Redis and Rate limiter clients to reuse and initialise them once. Then we initialise them in the initClients().

In main(), first, we load the environment variables from the system or the .env file. Then we call initClients(). This will create clients and store them in the variables we created.

Next, we create a Gin router that handles all our incoming requests. These are the environment variables we need in our .env file. For this demo, we need a Redis instance running to store all the data for rate-limiting functionality. We can use Docker or any remote machine – just remember to update REDIS_URL accordingly. I am going to use Docker.

We could also go a mile ahead and get all the environment variables from the feature flags, but we won’t do this here.

REDIS_URL=localhost:6379
PORT=8080
RATE_LIMIT=10

Creating Endpoints for the API

r.GET("/ping", func(c *gin.Context) {
        err, remainingLimit := rateLimitCall(c.ClientIP())
        if err != nil {
            c.JSON(
                http.StatusTooManyRequests,
                gin.H{"error": "Rate Limit Hit"})
        } else {
            c.JSON(
                http.StatusOK,
                gin.H{"Your left over API request is": remainingLimit})
        }
    })
    r.GET("/beta", func(c *gin.Context) {
        c.JSON(
            http.StatusOK,
            gin.H{"message": "This is beta endpoint"})
    })
    r.Run(":" + os.Getenv("PORT"))

Then we create two GET endpoints, /ping and /beta. Every time someone hits the /ping endpoint we call the rateLimitCall() function. It checks and sets the rate limit of incoming requests from an IP address. All this is stored in the Redis instance we created.

So, now if the user has interacted with the /ping API endpoint for the first time, will create an entry with a limit of 10 per hour. The limit number 10 comes from the RATE_LIMIT we set, and the hourly refresh form comes from the redis_rate.PerHour(RATE_LIMIT) function.

Next, we check if the user has a remaining limit. If yes, we will return a message with the number of requests they have remaining. Otherwise, if they hit the limit cap, we return a message letting them know this.

Apart from the /ping endpoint, we have another endpoint /beta. It returns a simple message, but later we’ll see how (using feature flags) we can completely turn on and off the functionality of this endpoint.

How to Add Feature Flagging

Now it’s time to add feature flagging capabilities to our app. We are going to use Flagsmith. Flagsmith is an open source software that lets us easily create and manage feature flags across web, mobile, and server-side applications.

Using Flagsmith, we can wrap features in a flag and then toggle them on or off for different environments, users, or user segments. And then you’ll be able to manage all of them from the Flagsmith dashboard without needing to redeploy.

So, let’s install the Flagsmith package by running the below command:

go get github.com/Flagsmith/flagsmith-go-client/v3

Then we import the package by giving it an alias flagsmith. Below is the updated functionality after we apply feature flagging to our existing code.

Let’s understand the changes we’ve made here (I’ll explain below the code snippet):

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "net/http"
    "os"

    flagsmith "github.com/Flagsmith/flagsmith-go-client/v3"
    "github.com/gin-gonic/gin"
    "github.com/go-redis/redis_rate/v10"
    "github.com/joho/godotenv"
    "github.com/redis/go-redis/v9"
)

var (
    redisClient     *redis.Client
    limiter         *redis_rate.Limiter
    flagsmithClient *flagsmith.Client
)

func initClients() {
    redisClient = redis.NewClient(&redis.Options{
        Addr: os.Getenv("REDIS_URL"),
    })
    limiter = redis_rate.NewLimiter(redisClient)
    flagsmithClient = flagsmith.NewClient(os.Getenv("FLAGSMITH_ENVIRONMENT_KEY"))
}

func main() {
    err := godotenv.Load()
    if err != nil {
        log.Printf("Loading environment variable from the host system")
    } else {
        log.Printf("Loading environment from .env file")
    }

    initClients()
    defer redisClient.Close()

    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        err, remainingLimit := rateLimitCall(c.ClientIP())
        if err != nil {
            c.JSON(
                http.StatusTooManyRequests,
                gin.H{"error": "Rate Limit Hit"})
        } else {
            c.JSON(
                http.StatusOK,
                gin.H{"Your left over API request is": remainingLimit})
        }
    })
    r.GET("/beta", func(c *gin.Context) {
        flags := getFeatureFlags()
        isEnabled, _ := flags.IsFeatureEnabled("beta")
        if isEnabled {
            c.JSON(
                http.StatusOK,
                gin.H{"message": "This is beta endpoint"})
        } else {
            c.String(http.StatusNotFound, "404 page not found")
        }
    })

    r.Run(":" + os.Getenv("PORT"))
}

func rateLimitCall(ClientIP string) (error, int) {

    ctx := context.Background()

    flags := getFeatureFlags()
    rateLimitInterface, _ := flags.GetFeatureValue("rate_limit")
    RATE_LIMIT := int(rateLimitInterface.(float64))
    fmt.Println("Current Rate Limit is", RATE_LIMIT)

    res, err := limiter.Allow(ctx, ClientIP, redis_rate.PerHour(RATE_LIMIT))
    if err != nil {
        panic(err)
    }

    if res.Remaining == 0 {
        return errors.New("You have hit the Rate Limit for the API. Try again later"), 0
    }

    fmt.Println("remaining request for", ClientIP, "is", res.Remaining)
    return nil, res.Remaining
}

func getFeatureFlags() flagsmith.Flags {
    ctx := context.Background()
    flags, _ := flagsmithClient.GetEnvironmentFlags(ctx)
    return flags
}

Understanding the Feature Flag Code Logic

func getFeatureFlags() flagsmith.Flags {
    ctx := context.Background()
    flags, _ := flagsmithClient.GetEnvironmentFlags(ctx)
    return flags
}

First, let’s directly jump to the new getFeatureFlags() function we created at the bottom. This function will return all the flags we created on the Flagsmith dashboard, by calling the GetEnvironmentFlags() method on flagsmithClient.

We initiated the flagsmithClient inside the initClients() function. The Flagsmith Client needs the access key (the NewClient() function) that we can get from the Flagsmith dashboard. As we did for the Redis and Limter clients, we will store the client in a global variable for reusability. You’ll understand the dashboard, creating flags, and retrieving the key in later steps.

func rateLimitCall(ClientIP string) (error, int) {

    ctx := context.Background()

    flags := getFeatureFlags()
    rateLimitInterface, _ := flags.GetFeatureValue("rate_limit")
    RATE_LIMIT := int(rateLimitInterface.(float64))
    fmt.Println("Current Rate Limit is", RATE_LIMIT)

    res, err := limiter.Allow(ctx, ClientIP, redis_rate.PerHour(RATE_LIMIT))
    if err != nil {
        panic(err)
    }

    if res.Remaining == 0 {
        return errors.New("You have hit the Rate Limit for the API. Try again later"), 0
    }

    fmt.Println("remaining request for", ClientIP, "is", res.Remaining)
    return nil, res.Remaining
}

Now coming to the rateLimitCall() function, instead of getting RATE_LIMIT from the environment, we get the value from the rate_limit flag (that we will create later). We call getFeatureFlags() and get the flag rate_limit value out from all the flags.

By setting these as feature flags, we can dynamically change the limit anytime from the dashboard. We don’t need to change the code’s functionality or do it the traditional way by changing the RATE_LIMIT value and re-running the server so that it catches new updated values.

    r.GET("/beta", func(c *gin.Context) {
        flags := getFeatureFlags()
        isEnabled, _ := flags.IsFeatureEnabled("beta")
        if isEnabled {
            c.JSON(
                http.StatusOK,
                gin.H{"message": "This is beta endpoint"})
        } else {
            c.String(http.StatusNotFound, "404 page not found")
        }
    })

Now coming to the /beta endpoint, based on whether the beta flag is enabled or disabled, this endpoint will serve the query. Otherwise, it will act as a non-reachable endpoint and return a 404 error message.

In our example, I have added a basic placeholder message to show how it will work, but this opens new possibilities in testing and initial releases (beta). If the API has a new endpoint, we can wrap the functionality in the feature flag and make it available and unavailable with a single click of a button. Also, we can do a lot more like scheduling and canary releases.

Also, our .env file will look like this. We have removed RATE_LIMIT and added FLAGSMITH_ENVIRONMENT_KEY.

REDIS_URL=localhost:6379
PORT=8080
FLAGSMITH_ENVIRONMENT_KEY=ser.ZRd***********469

How to Create Feature Flags in the Flasgsmith Dashboard

Let’s head to the Flagsmith dashboard to create the flags we used above and get the access key. If you don’t have a Flagsmith account you can sign up for free here.

After you sign up you will be prompted to create an organisation and a project. Project separation is good, as it helps us isolate logic for different projects. Once you are done, you will see a dashboard, just like the screenshot below.

We have loads of functionalities from integrations to scheduling the flags to compare the changes. Apart from Go, Flagsmith provides many SDKs. You can click on where the language name is written and it will give you some boilerplate code for that language.

Rate Limiting Feature Flag

Now, let's create our first feature flag for the rate limit. Click on the Create Feature button in the top right corner. A sidebar window will open up. Set the name, then to make the flag turn on the right way while creating, we can select Enabled by default.

In the value section, we need to set the flag value. It can take formats like Txt, JSON, XML, and so on. As our feature value is simple text like 20, 30, and so on, we will choose Txt (the default one) and set a random limit – we’ll go with 20.

You can also give tags and descriptions. Tags can be helpful when filtering out the Feature Flags. For example, we can create a tag backend to filter out all the feature flags related to Backend. The description is a concise explanation of what this particular future flag does when it is enabled (and will help with future understanding).

The screenshot below shows how it will look after filling in the details. Then, click on the Create Feature button to create the flag.

Beta Feature Flag

Let’s now create a second, beta feature flag. It will be the same process as the first one, but in this one, we don’t need to set any flag value and leave that column empty. Once we create both flags, our dashboard will look like this. It shows the flag name, value, current state (view), and so on.

Getting the Access Key

To get the Access Key, click on the SDK Keys from the sidebar, and click the Create Server-side Environment Key button to generate a key. As our app is server-side, it’s good to use that one only. Then copy and paste that key into the value placed in .env for the FLAGSMITH_ENVIRONMENT_KEY key.

Running the API

Now everything is set, so let’s head over back to IDE and run the server by executing the go run main.go command in the terminal. We will see this message In the terminal. In case you encounter any errors, just check that the packages are correctly installed, the variables are correctly set, and the app accesses the Redis instance.

Now if we visit localhost:8080/ping, we will get a message {"Your left over API request is":19}. The limit was 20, we did one request now, and the remaining is 19.

Updating the `rate_limit` Flag

Let’s update the rate_limit flag value to 10 and see what happens. To do so, again visit the Flagsmith dashboard and click on the flag name. A side menu bar will open. Update the value to 10, and click on the Update Feature Value button.

We can also schedule the update. For example, this can be useful when we expect a spike in traffic at a certain timeframe and reduce the limit per user to reduce server load.

If you now visit localhost:8080/ping, you will get a message {"Your left over API request is":8} – because the total limit is 10 and we have already requested two times.

Let's now test the /beta endpoint. Visit localhost:8080/beta, and we will see a message {"message":"This is beta endpoint"}.

Now go back to the Flagsmith dashboard and toggle the switch to disable this flag. Now visit the the URL. You will get a 404 message like this endpoint never existed.

Now that we’ve set up the functionality and demoed the feature flagging capabilities, let’s see how we can integrate the Flasgsmith GitHub App.

How to Integrate Feature Flags with the GitHub App

First, make sure you have pushed your app to GitHub. After that, install the GitHub Flasgsmith App on your repo from the GitHub Marketplace.

By integrating GitHub and Falagsmith, we can view updates on your feature flags/features as comments in GitHub Issues and Pull Requests. This allows us to easily track features, from creating an issue to merging a PR and deploying the changes.

Then select your organisation and the repositories where you want to install the app. You can install it on all of your repos or select a particular one.

As you install it, you will be auto-redirected to the Flagmsith dashboard to configure and complete the integration. Most of the data will be pre-populated, so you just need to select and add a project, and then save the configuration.

Once you hit the Save Configuration Button, it will redirect you back to the main Flagsmith dashboard where we were previously working.

Now let’s link one of the existing flags with the GitHub issue/pull request (raise a dummy PR/issue to test it), or you can create a new flag to test. Let’s proceed with the beta flag which we already created for the beta endpoint.

To link the flag with an existing issue or a pull request, click on the flag name, and a side menu will pop up from the right. Then, choose the 'Link' tab. Then select the Pull Request option, and choose the Pull Request you want to link. All of your Issues and Pull Requests linked to this flag are visible below:

To verify that the flag is successfully linked, click the hyperlink with the arrow icon below the Name column heading. It will navigate you to that particular Issue/Pull Request on GitHub. You can see that the Flagsmith GitHub App has commented below with all the details, such as environment, enabled value, and so on.

Testing the Flagsmith GitHub App

After this, when you make any changes to the flag settings, such as turning on/off the flag or changing the value, the bot will comment with all the updated details.

Let’s test by turning the flag off. As soon as you turn off the flash from the Dashboard, the bot should comment that the flag has now been disabled:

That’s it. That is how it’s simple to integrate Flagsmith with GitHub.

Conclusion

To sum it up, you now know how you can leverage feature flags as a backend developer to change the functionality of your app on the fly.

To take things to the next level, we integrated our demo app with the Flagsmith GitHub app so it could stay updated with the changes to our feature flags’ status on Pull Requests/Issues without having to manually update them.

Check out the Flagsmith repo here and don't forget to give each of these projects a star to show your support. You can also join their amazing community to get technical support.

You can connect with me - Pradumna Saraf, on socials here.

feature flags - freeCodeCamp.org

How to Build a Production-Ready Feature Flag System with Next.js and Supabase

Table of Contents

Prerequisites

What Are Feature Flags?

Project Setup

Database Schema Design

Setting Up Supabase

Step 1: Create a Supabase Project

Step 2: Run the Migration

Step 3: Get Your API Credentials

Building the Core Feature Flag Logic

TypeScript Types

Supabase Client Setup

Client-Side Feature Flag Logic

Server-Side Feature Flag Logic

Setting Up React Query

Create the Query Provider

Add Provider to Root Layout

What QueryProvider actually does

Creating the React Hook

Admin Hooks for Managing Flags

Step 1: Create the hooks file

Step 2: Add a hook to fetch all feature flags

Step 3: Add a hook to update a feature flag

Step 4: Add a hook to delete a feature flag

Step 5: Add a hook to create a new feature flag

Feature Flag Gate Component

Building the Admin Dashboard

Step 1: Create the main feature flags API route

Step 2: Create the dynamic route for individual flags

Step 3: Create the Admin Dashboard UI

'text-3xl font-bold text-gray-900'> Feature Flags Admin

Using Feature Flags Mutations in Components

"text-lg font-semibold text-gray-900"> {flag.name}

Implementing a Real-World Example

Step 1: Create the Todo Page File

Step 2: Initialize state in the component

Step 3: Load and save todos from localStorage

Step 4: Add helper functions

Step 5: Render the Todo App inside the FeatureFlagGate

Step 6: Add the input field and Add button

Step 8: Display the list of todos

Todo App Overview

Server-Side Usage

Why React Query?

Real-World Impact

Conclusion

How to Build a Flexible API with Feature Flags Using Open Source Tools

Here’s what we’ll cover:

Prerequisites

What is a Feature Flag?

Feature Flags for Backend Development

Why Use Open Source Tools?

Let’s Code!

Initializing the Tools

Creating Endpoints for the API

How to Add Feature Flagging

Understanding the Feature Flag Code Logic

How to Create Feature Flags in the Flasgsmith Dashboard

Rate Limiting Feature Flag

Beta Feature Flag

Getting the Access Key

Running the API

Updating the rate_limit Flag

How to Integrate Feature Flags with the GitHub App

Testing the Flagsmith GitHub App

Conclusion

What `QueryProvider` actually does

Updating the `rate_limit` Flag