Home - nicokempe/nuxt-feature-flags-module GitHub Wiki

Welcome to the official documentation for the Nuxt Feature Flags Module, a lightweight and flexible feature flag system for Nuxt. It helps you control what features are shown or hidden based on environments, scheduled dates, and even A/B variants.

Installation

Install the module with the Nuxt CLI:

npx nuxi module add nuxt-feature-flags-module

Or manually via pnpm, npm, bun, or yarn:

pnpm add -D nuxt-feature-flags-module

Then, add it to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-feature-flags-module'],
  featureFlags: {
    environment: process.env.FEATURE_ENV || 'development',
    flagSets: {
      development: ['newDashboard', 'betaSettings'],
      staging: ['newDashboard'],
      production: []
    }
  }
})

Configuration

Basic

environment: The current environment (string).
flagSets: Map of environment → feature flags.

Advanced (Optional)

featureFlags: {
  environment: 'production',
  flagSets: { ... },
  validation: {
    mode: 'warn', // 'disabled' | 'warn' | 'error'
    includeGlobs: ['**/*.vue', '**/*.ts'],
    excludeGlobs: ['node_modules', '.nuxt', 'dist']
  }
}

Usage

In Templates (with Directive)

<template>
  <button v-feature="'betaSettings'">Try the new Settings</button>
</template>

In Scripts (with Composable)

const { isEnabled } = useFeatureFlag()

if (isEnabled('newDashboard')) {
  // Activate experimental feature
}

In API Routes

import { isFeatureEnabled } from '#imports'

export default defineEventHandler((event) => {
  if (!isFeatureEnabled('betaSettings', event)) {
    return sendError(event, createError({ statusCode: 403, message: 'Not allowed' }))
  }
  return { ok: true }
})

Middleware

definePageMeta({
  middleware: ['feature-betaSettings']
})

// or define your own:
export default defineFeatureFlagMiddleware('betaSettings')

A/B Testing Support

You can define variants for a feature:

featureFlags: {
  flagSets: {
    development: [
      {
        name: 'uiExperiment',
        variants: ['a', 'b'],
        distribution: [0.5, 0.5],
        persistence: 'cookie' // or 'state', 'local'
      }
    ]
  }
}

Use useFeatureVariant() to get the current variant:

const variant = useFeatureVariant('uiExperiment')
if (variant === 'a') showOldUI()
else showNewUI()

Validation

All feature usage (e.g. v-feature, isEnabled) is scanned and validated:

warn (default): logs warnings
error: fails the build
disabled: no validation

Each usage includes file path, line, and column.