Lightweight, environment-based feature flag system for Nuxt - made for developers who need dynamic feature control in routes, components, and APIs.

Features

• 🚫 Hide incomplete features in production environments to prevent accidental exposure
• 🧪 Enable alpha/beta features for staging, preview, or development environments
• 🔐 Limit access to specific APIs by feature flag in server handlers
• 🎯 Roll out features to internal QA teams without branching or releases
• 📆 Schedule feature launches for specific environments or timeframes
• 🕵️‍♀️ Detect undeclared feature flags at build time with configurable validation and precise file context
• 🌳 Group flags with hierarchical names and enable bundles via wildcard (*) patterns

Planned Features

• 📊 A/B testing support for feature flags
• 💡 Flag descriptions / metadata for better documentation, DevTools tooltips, or internal usage notes
• 🧩 Nuxt DevTools integration with a Feature Flag Explorer and Environment Switcher
• 🔄 Dynamic feature flag updates without server restarts through a remote config service
• 🧍‍♂️ Show features only for specific users (e.g., staff-only UIs, admin panels etc.)
• 🛠 Programmatic overrides to toggle or override feature flags dynamically at runtime (e.g., per user or session)
• 📈 Analytics for feature flag usage and user feedback collection

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-feature-flags-module

That's it! You can now use Nuxt Feature Flags in your Nuxt app ✨

Then define your feature flags in nuxt.config.ts:

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

Hierarchical & Wildcard Flags

Feature flags can be organized with /-separated paths and enabled in bulk using *.

export default defineNuxtConfig({
  modules: ['nuxt-feature-flags-module'],
  featureFlags: {
    environment: process.env.FEATURE_ENV || 'development',
    flagSets: {
      development: [
        'solutions/*',
        'staging/*',
        'internal/experimental/ui'
      ],
      staging: [
        'solutions/company-portal/addons/sales',
        'solutions/company-portal/addons/marketing',
        'internal/experimental/ui'
      ],
      production: [
        'solutions/company-portal/addons/sales'
      ]
    }
  }
})

const { isEnabled } = useFeatureFlag()

if (isEnabled('solutions/company-portal/addons/sales')) {
  // sales addon enabled
}

if (isEnabled('solutions/*')) {
  // any solution-related flag is active
}

Caution

Using * enables every flag and the validator will emit a warning. Reserve it for debugging scenarios.

Use in your app:

<template>
  <button v-feature="'yourFeature1'">Try Feature 1</button>
</template>

Or via composable:

const { isEnabled, listFlags } = useFeatureFlag()

if (isEnabled('yourFeature2')) {
  // do something
}

console.log(listFlags()) // returns ['yourFeature1', 'yourFeature2', 'yourFeature3', 'yourFeature4']

Or in your server API:

export default defineEventHandler((event) => {
  if (!isFeatureEnabled('yourFeature3', event)) {
    return sendError(event, createError({ statusCode: 403, message: 'Feature 3 is disabled' }))
  }

  return { message: 'Feature unlocked 🎉' }
})

Or guard entire pages via definePageMeta:

<script lang="ts">
definePageMeta({
  featureFlag: 'yourFeature4',
  featureFallback: '/404',
  featureNotifyOnBlock: true,
})
</script>

Contribution

Local development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Validate release tooling
pnpm run release:check

Releases

Maintainers publish the public npm package and matching GitHub Release from the Release package workflow. Versioning, credentials, and retry behavior are documented in RELEASING.md.

License

This project is licensed under the MIT License.