A feature flag module for Nuxt 3 with context-aware evaluation and server-side support, inspired by @happykit/flags.
- 🎯 Context-aware evaluation (user, environment, cookies)
- ⚡ Server-side evaluation
- 🛠 TypeScript ready
- 🔍 Explanation system for flag states
- 🧩 Nuxt 3 composables integration
- 🔧 Runtime configuration support
- 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>
interface ModuleOptions {
flags?: Record<string, FlagDefinition>
defaultContext?: Record<string, any>
envKey?: string
contextPath?: string
}
// 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'
}
})
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.
const {
flags, // Reactive flags object
isEnabled, // (flagName: string) => boolean
get // <T>(flagName: string) => Flag<T> | undefined
} = useFeatureFlags()
type FlagDefinition =
| boolean
| ((context: EvaluationContext) => boolean)
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
MIT License © 2025 Roberth González