Feature Flags

Control feature rollouts, A/B testing, and gradual deployments with the Flags SDK integration. Orbitus provides a seamless integration with Vercel’s Flags SDK for type-safe feature flag management.

📦 Installation

The Flags SDK is included in @orbitusdev/core. No additional installation required.


# Already included in @orbitusdev/core
pnpm add @orbitusdev/core

🚀 Quick Start

Basic Usage


import { showNewDashboard } from '@orbitusdev/core/flags';
 
// In a Server Component or Server Action
export default async function DashboardPage() {
  const isNewDashboard = await showNewDashboard();
 
  return isNewDashboard ? <NewDashboard /> : <OldDashboard />;
}

Available Flags

Orbitus comes with pre-configured feature flags:

Flag	Description	Default
`showNewDashboard`	Enable the new dashboard UI	`false`
`enableBetaFeatures`	Enable beta features for testing	`false`
`maintenanceMode`	Put the application in maintenance mode	`false`
`darkModeDefault`	Use dark mode as the default theme	`false`
`analyticsEnabled`	Enable analytics tracking	`true`

🛠️ Creating Custom Flags

Define a New Flag

Create flags in packages/core/src/flags/config.ts:


import { flag } from 'flags/next';
 
export const myNewFeature = flag({
  key: 'my-new-feature',
  decide: () => false, // Default value
  description: 'Enable my new feature',
  options: [true, false],
});

Export the Flag

Add to packages/core/src/flags/index.ts:


export { myNewFeature } from './config';

Use in Your Application


import { myNewFeature } from '@orbitusdev/core/flags';
 
const isEnabled = await myNewFeature();

🎯 Advanced Usage

User-Targeted Flags

Create flags that depend on user context:


import { flag } from 'flags/next';
import { getCurrentUser } from '@orbitusdev/auth';
 
export const premiumFeatures = flag({
  key: 'premium-features',
  decide: async () => {
    const user = await getCurrentUser();
    return user?.subscription === 'premium';
  },
  description: 'Enable premium features for subscribed users',
  options: [true, false],
});

Percentage Rollouts

Gradually roll out features to a percentage of users:


import { flag } from 'flags/next';
 
export const newCheckout = flag({
  key: 'new-checkout',
  decide: async ({ headers, cookies }) => {
    // Get user identifier from cookies or headers
    const userId = cookies.get('userId')?.value;
    if (!userId) return false;
    
    // Simple percentage-based rollout (20% of users)
    const hash = simpleHash(userId);
    return hash % 100 < 20;
  },
  description: 'New checkout experience',
  options: [true, false],
});
 
function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) - hash) + str.charCodeAt(i);
    hash = hash & hash;
  }
  return Math.abs(hash);
}

Environment-Based Flags

Enable features only in specific environments:


import { flag } from 'flags/next';
 
export const debugMode = flag({
  key: 'debug-mode',
  decide: () => process.env.NODE_ENV === 'development',
  description: 'Enable debug mode',
  options: [true, false],
});

📱 Client-Side Usage

Precomputing Flags

For optimal performance, precompute flags on the server and pass to client:


// app/layout.tsx
import { precompute } from 'flags/next';
import { allFlags } from '@orbitusdev/core/flags';
 
export default async function RootLayout({ children }) {
  const flags = await precompute(allFlags);
  
  return (
    <html>
      <body data-flags={JSON.stringify(flags)}>
        {children}
      </body>
    </html>
  );
}

Reading Precomputed Flags


// components/feature-toggle.tsx
'use client';
 
export function FeatureToggle() {
  const flags = JSON.parse(
    document.body.dataset.flags || '{}'
  );
  
  return flags['new-dashboard'] ? <NewUI /> : <OldUI />;
}

When deployed to Vercel, you can use the Vercel Toolbar to:

View all active feature flags
Override flags for testing
See flag values in real-time

📚 API Reference

`flag(options)`

Creates a new feature flag.


interface FlagOptions<T> {
  key: string;              // Unique identifier
  decide: () => T | Promise<T>;  // Resolution function
  description?: string;     // Human-readable description
  options?: T[];           // Possible values (for UI)
}

`precompute(flags)`

Precomputes all flag values for client-side usage.


import { precompute } from 'flags/next';
import { allFlags } from '@orbitusdev/core/flags';
 
const computedFlags = await precompute(allFlags);
// Returns: { 'new-dashboard': false, 'beta-features': false, ... }

💡 Best Practices

Keep flags temporary: Remove flags once features are fully rolled out
Use descriptive keys: new-checkout-v2 is better than flag1
Document flags: Always add descriptions for team visibility
Test both states: Ensure your app works with flags on and off
Monitor flag usage: Track which flags are active in production