nuxt-feature-flags-module

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

Planned Features

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

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: []
    }
  }
})

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

# Release new version
pnpm run release

License

This project is licensed under the MIT License.

Changelog

v2025.6.2

compare changes

🚀 Enhancements

• middleware: Add page-level feature flag protection via definePageMeta (#77)

🩹 Fixes

• package: Update Git repository url from npm fix (1b6e6f4)

💅 Refactors

• config: Rename environments to flags in feature flag configuration (d298505)
• config: Rename flags to flagSets in feature flag configuration (14ceeaa)

📖 Documentation

• dx: Add update labels for dependabot pull requests (98eea2e)
• readme: Add total downloads (18m) (ca78c46)
• nuxt: Remove nuxt version specification (9cab437)
• conduct: Add code of conduct (3898f7f)
• contributing: Add contribution guide (732da43)
• contributing: Add note on how to bump the project version (1a52568)
• features: Update examples in README (cef560f)

🏡 Chore

• pnpm: Update packages (c7c80d8)
• pnpm: Bump changelogen from 0.6.1 to 0.6.2 (#49)
• pnpm: Bump @types/node from 24.0.10 to 24.0.13 (#51)
• pnpm: Bump tmp from 0.2.3 to 0.2.4 in the npm_and_yarn group (#73)
• pnpm: Update packages (c539f2c)
• actions: Bump actions/checkout from 4 to 5 (#74)
• pnpm: Update packages (a45e3de)
• pnpm: Update packages (29623ca)
• config: Add missing compatibility dates (b543651)

✅ Tests

• flagValidator: Add unit tests for feature flag validation (4568e74)
• isFeatureEnabled: Add unit tests for feature flag evaluation (effb7f5)
• isFlagActiveNow: Add unit tests for flag activation logic (ad8c6b3)
• useFeatureFlag: Add unit tests for feature flag detection and scheduling (ee72e7e)

🤖 CI

• Add workflow_dispatch trigger (9c636be)
• security: Restrict GITHUB_TOKEN permissions to contents:read (183430a)
• dependabot: Update commit message prefixes for pnpm and actions (099fae1)

❤️ Contributors

• Nico Kempe (@nicokempe)