Getting Started

Installation

Add Nuxt Feature Flags to your project using the Nuxt CLI:

npx nuxi module add nuxt-feature-flags

Or manually install it using your package manager:

# Using npm
npm install nuxt-feature-flags

# Using yarn
yarn add nuxt-feature-flags

# Using pnpm
pnpm add nuxt-feature-flags

Requirements: Nuxt 3.1.0 or higher

Quick Setup

Choose the configuration method that best fits your needs:

Method 1: Inline Configuration (Simplest)

Best for simple projects with a small number of static flags:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-feature-flags'],
  featureFlags: {
    flags: {
      newDashboard: false,
      experimentalFeature: true,
      darkMode: true
    }
  }
})

When to use: Quick prototypes, simple feature toggles, or when you have fewer than 10 flags.

Method 2: Configuration File (Recommended)

Best for most projects. Keep your flags organized in a dedicated configuration file:

// feature-flags.config.ts
import { defineFeatureFlags } from '#feature-flags/handler'

export default defineFeatureFlags(() => ({
  newDashboard: true,
  experimentalFeature: process.env.NODE_ENV === 'development',
  betaFeature: false,
  
  // A/B test with variants
  buttonDesign: {
    enabled: true,
    value: 'default',
    variants: [
      { name: 'control', weight: 50, value: 'original' },
      { name: 'treatment', weight: 50, value: 'new-design' }
    ]
  }
}))

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-feature-flags'],
  featureFlags: {
    config: './feature-flags.config.ts'
  }
})

When to use: Production applications, when you need environment-based flags, or when managing multiple flags.

Method 3: Context-Aware Configuration (Advanced)

Best for dynamic flags that depend on user attributes, request context, or runtime conditions:

// feature-flags.config.ts
import { defineFeatureFlags } from '#feature-flags/handler'

export default defineFeatureFlags((context) => {
  return {
    // User role-based flag
    isAdmin: context?.user?.role === 'admin',
    
    // Environment-based flag
    devTools: process.env.NODE_ENV === 'development',
    
    // User status-based flag
    betaFeature: context?.user?.isBetaTester ?? false,
    
    // Device-based flag
    mobileFeature: context?.device?.isMobile ?? false,
    
    // Gradual rollout (30% get new feature)
    newCheckout: {
      enabled: true,
      variants: [
        { name: 'old', weight: 70, value: false },
        { name: 'new', weight: 30, value: true }
      ]
    }
  }
})

When to use: Personalized features, role-based access, A/B testing, or when flags need to evaluate differently per user/request.

Usage Examples

Client-Side Usage

<script setup>
const { isEnabled, getVariant, getValue } = useFeatureFlags()
</script>

<template>
  <div>
    <!-- Simple feature flag -->
    <NewDashboard v-if="isEnabled('newDashboard')" />
    
    <!-- A/B test with variants -->
    <div v-feature="'buttonDesign:control'">
      <button class="original-style">Click me</button>
    </div>
    <div v-feature="'buttonDesign:treatment'">
      <button class="new-style">Click me</button>
    </div>
    
    <!-- Check specific variant programmatically -->
    <div v-if="getVariant('buttonDesign') === 'treatment'">
      You're seeing the new design!
    </div>
  </div>
</template>

Server-Side Usage

// server/api/dashboard.ts
export default defineEventHandler(async (event) => {
  const { isEnabled, getVariant, getValue } = getFeatureFlags(event)

  if (!isEnabled('newDashboard')) {
    throw createError({
      statusCode: 404,
      message: 'Dashboard not available'
    })
  }

  // Check if user is in new checkout variant
  const checkoutVersion = getVariant('newCheckout')
  
  return {
    stats: {
      users: 100,
      revenue: 50000
    },
    checkoutVersion,
    useNewFeatures: getValue('newCheckout')
  }
})

TypeScript Support

The module automatically generates TypeScript types from your flag configuration:

const { isEnabled } = useFeatureFlags()

isEnabled('newDashboard')     // ✅ Type-safe - flag exists
isEnabled('unknownFlag')      // ❌ TypeScript error - flag not declared

No additional setup required! Types are regenerated whenever your flag configuration changes.

Next Steps

• Learn about Context-Aware Flags for dynamic evaluation
• Explore Variants & A/B Testing for gradual rollouts
• Check the API Reference for all available methods
• Review Best Practices for effective flag management