nuxt-feature-flags

Nuxt Feature Flags 🚩

A powerful, type-safe feature flag module for Nuxt 3 that enables both static and dynamic feature flag evaluation with server-side support. Perfect for A/B testing, gradual rollouts, and feature management.

✨ Features

• ⚡ Server-Side Support: Evaluate flags on the server for consistent behavior, better performance, and SEO optimization
• 🛠 TypeScript Ready: Full TypeScript support with type-safe flag definitions and autocomplete
• 🔍 Explanation System: Understand why flags are enabled/disabled with detailed explanations
• 🧩 Nuxt 3 Integration: Seamless integration with auto-imports and runtime config
• 🎯 Static & Dynamic Flags: Support for both simple boolean flags and dynamic evaluation
• 🔒 Type Safety: Catch errors early with full type inference and validation

📦 Installation

# Using npx
npx nuxi module add nuxt-feature-flags

# Using npm
npm install nuxt-feature-flags

# Using yarn
yarn add nuxt-feature-flags

# Using pnpm
pnpm add nuxt-feature-flags

🚀 Quick Setup

• Add the module to your nuxt.config.ts:

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

• Use in your Vue components:

<script setup>
const { isEnabled, get } = useClientFlags()
</script>

<template>
  <div>
    <NewDashboard v-if="isEnabled('newDashboard')" />
    <div v-if="get('experimentalFeature')?.explanation">
      Flag enabled because: {{ get('experimentalFeature').explanation.reason }}
    </div>
  </div>
</template>

• Use in your server routes:

// server/api/dashboard.ts
export default defineEventHandler((event) => {
  const { isEnabled } = useServerFlags(event)

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

  return {
    stats: {
      users: 100,
      revenue: 50000
    }
  }
})

📖 Documentation

Visit our documentation site for detailed guides and API reference.

Client-Side Usage

const { 
  flags,       // Reactive flags object
  isEnabled,   // (flagName: string) => boolean
  get          // <T>(flagName: string) => Flag<T> | undefined
} = useClientFlags()

// Check if a flag is enabled
if (isEnabled('newFeature')) {
  // Feature is enabled
}

// Get flag with explanation
const flag = get('experimentalFeature')
console.log(flag.explanation)

Server-Side Usage

const { 
  flags,       // Flags object
  isEnabled,   // (flagName: string) => boolean
  get          // <T>(flagName: string) => Flag<T> | undefined
} = useServerFlags(event)

// Check if a flag is enabled
if (isEnabled('newFeature')) {
  // Feature is enabled
}

// Get flag with explanation
const flag = get('experimentalFeature')
console.log(flag.explanation)

Flag Types

interface Flag<T = boolean> {
  value: T
  explanation?: {
    reason: 'STATIC' | 'TARGETING_MATCH' | 'DEFAULT'
    rule?: string
  }
}

⚙️ Configuration

interface FeatureFlagsConfig {
  flags?: FlagDefinition // Feature flags object
  config?: string // Path to configuration file
}

type FlagDefinition = Record<string, boolean>

// Example of inline configuration
export default defineNuxtConfig({
  featureFlags: {
    flags: {
      promoBanner: true,
      betaFeature: false,
      newDashboard: false
    }
  }
})

// Example of configuration file
// feature-flags.config.js
export default {
  isAdmin: false,
  newDashboard: true,
  experimentalFeature: true,
  promoBanner: false,
  betaFeature: false,
}

// nuxt.config
export default defineNuxtConfig({
  featureFlags: {
    flags: {
      config: './feature-flags.config.js',
    }
  }
})

🤝 Contributing

• Clone this repository
• Install dependencies using npm install
• Start development server using npm run dev
• Make your changes
• Submit a pull request

📄 License

MIT License © 2025 Roberth González