Configuration Options

This page lists and explains all available configuration options for the nuxt-feature-flags-module in your nuxt.config.ts file.

featureFlags

The module is configured under the featureFlags key. This object must be added to your Nuxt configuration.

export default defineNuxtConfig({
  modules: ['nuxt-feature-flags-module'],
  featureFlags: {
    environment: 'development',
    flagSets: {
      development: ['featureA'],
      production: []
    },
    validation: {
      mode: 'warn'
    }
  }
})

environment: string

The name of the current environment, used to determine which feature flags are active.

• Example: 'production', 'staging', 'development'

• Usually driven by an environment variable:

  environment: process.env.FEATURE_ENV || 'development'

flagSets: Record<string, FeatureFlagInput[]>

Defines which flags are enabled for each environment. Each flag can be either a simple string or a full object with advanced options.

flagSets: {
  development: [
    'featureA',
    {
      name: 'featureB',
      activeFrom: '2025-06-01T00:00:00Z',
      activeUntil: '2025-07-01T00:00:00Z'
    },
    {
      name: 'uiTest',
      variants: ['a', 'b'],
      distribution: [0.2, 0.8],
      persistence: 'cookie'
    }
  ]
}

FeatureFlagInput

type FeatureFlagInput = string | FeatureFlag

FeatureFlag

interface FeatureFlag {
  name: string
  activeFrom?: string         // ISO timestamp string (optional)
  activeUntil?: string        // ISO timestamp string (optional)
  variants?: string[]         // Optional A/B variants
  distribution?: number[]     // Probability per variant (must match length)
  persistence?: 'state' | 'cookie' | 'local' // Variant storage method
}

activeFrom and activeUntil

You can define time-based activation windows using ISO timestamps. The flag will only be considered "enabled" within this timeframe.

variants

List of A/B test variants (e.g., ['control', 'treatment']). Requires:

• distribution: Probability array (e.g., [0.5, 0.5])
• persistence: How the selected variant is stored

persistence

Persistence options for A/B variant storage:

• 'state': Vue state (default)
• 'cookie': Shared between client/server
• 'local': localStorage (client-only)

validation (optional)

Enable validation of used feature flags during development/build time.

validation: {
  mode: 'warn',
  includeGlobs: ['**/*.{vue,ts,js}'],
  excludeGlobs: ['node_modules', '.nuxt', 'dist']
}

mode: 'disabled' | 'warn' | 'error'

• 'disabled': Skip validation
• 'warn' (default): Print console warnings
• 'error': Throw build-time errors for undeclared or invalid flags

includeGlobs: string[]

Which files to scan. Defaults to:

['**/*.{vue,ts,js}']

excludeGlobs: string[]

Which paths to exclude from scanning. Defaults to:

['node_modules', '.nuxt', 'dist']