nuxt-feature-flags

Nuxt Feature Flags 🚩

A feature flag module for Nuxt 3 with context-aware evaluation and server-side support, inspired by @happykit/flags.

• ✨  Release Notes
• 📖  Documentation

Features

• 🎯  Context-aware evaluation (user, environment, cookies)
• ⚡  Server-side evaluation
• 🛠  TypeScript ready
• 🔍  Explanation system for flag states
• 🧩  Nuxt 3 composables integration
• 🔧  Runtime configuration support

Quick Setup

• Add the module to your Nuxt project:

npx nuxi module add nuxt-feature-flags

• Create a context file:

// ~/feature-flags.context.ts
import { parseCookies } from 'h3'
import { detectDevice } from '~/utils/device'

export default function featureFlagsContext(event: any) {
  return {
    user: event?.context.user,
    cookies: parseCookies(event),
    device: detectDevice(event),
    environment: process.env.NODE_ENV
  }
}

• Configure in nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-feature-flags'],
  featureFlags: {
    contextPath: '~/feature-flags.context',
    flags: {
      experimentalFeature: (context) => context.user?.isBetaTester
    },
    defaultContext: {
      environment: process.env.NODE_ENV
    }
  }
})

• Use in components:

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

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

Configuration

Module Options

interface ModuleOptions {
  flags?: Record<string, FlagDefinition>
  defaultContext?: Record<string, any>
  envKey?: string
  contextPath?: string
}

Example Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  featureFlags: {
    contextPath: '~/feature-flags.context',
    flags: {
      promoBanner: true,
      userSurvey: { percentage: 50 },
      betaFeature: (ctx) => ctx.user?.tier === 'premium'
    },
    defaultContext: {
      environment: process.env.NODE_ENV
    },
    envKey: 'NUXT_PUBLIC_FEATURE_FLAGS'
  }
})

Documentation

Context File

Create a file at the specified contextPath (default: ~/feature-flags.context.ts) that exports a function:

export default function featureFlagsContext(event: any) {
  return {
    // Your context properties
  }
}

The function receives the Nitro event and should return an object with the evaluation context.

Composables

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

Flag Definitions

type FlagDefinition =
  | boolean
  | ((context: EvaluationContext) => boolean)

Contribution

Contributions are welcome! Please follow these steps for local development:

# Install dependencies
npm install

# Develop with playground
npm run dev

# Lint code
npm run lint

License

MIT License © 2025 Roberth González