Nuxt Feature Flags

Type-safe feature flags for Nuxt 3 with runtime evaluation and built-in A/B testing.

Highlights

• Runtime flag resolution on server requests.
• Async config support (defineFeatureFlags(async () => ...)).
• Built-in variant assignment for experiments.
• Nuxt auto-imports for client and server helpers.
• Validation and test tooling for safer rollouts.

Installation

npx nuxi module add nuxt-feature-flags

Quick Start

1. Enable the module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-feature-flags'],
  featureFlags: {
    config: './feature-flags.config.ts',
  },
})

2. Define flags

// feature-flags.config.ts
import { defineFeatureFlags } from '#feature-flags/handler'

export default defineFeatureFlags(async () => {
  const remoteFlags = await $fetch('https://api.example.com/flags')

  return {
    newDashboard: true,
    checkoutExperiment: {
      enabled: true,
      value: 'control',
      variants: [
        { name: 'control', weight: 50, value: 'control' },
        { name: 'treatment', weight: 50, value: 'treatment' },
      ],
    },
    ...remoteFlags,
  }
})

3. Use flags in client and server

<script setup lang="ts">
const { flags, isEnabled } = useFeatureFlags()
const { flags: asyncFlags, pending, error } = useAsyncFeatureFlags()
</script>

<template>
  <NewDashboard v-if="isEnabled('newDashboard')" />

  <div v-if="pending">Loading flags...</div>
  <div v-else-if="error">Could not refresh flags</div>
  <CheckoutV2 v-else-if="asyncFlags.checkoutExperiment?.enabled" />
</template>

// server/api/data.ts
import { getFeatureFlags } from '#feature-flags/server/utils'

export default defineEventHandler(async (event) => {
  const { isEnabled, getVariant } = await getFeatureFlags(event)

  if (!isEnabled('newDashboard')) {
    throw createError({ statusCode: 404, statusMessage: 'Feature disabled' })
  }

  return {
    variant: getVariant('checkoutExperiment'),
  }
})

API

Client

• useFeatureFlags()

  • flags
  • isEnabled(flag)
  • getValue(flag)
  • getVariant(flag)

• useAsyncFeatureFlags()

  • flags
  • pending
  • error
  • refresh()

Server

• await getFeatureFlags(event)
  • flags
  • isEnabled(flag)
  • getValue(flag)
  • getVariant(flag)

Directive

<template>
  <div v-feature="'myFlag'">Only when enabled</div>
</template>

Migration Notes (v1 -> v2)

• Server resolution is async: await getFeatureFlags(event).
• Async config functions are supported.
• useAsyncFeatureFlags is available for client refresh states.
• useFeatureFlags reads already-resolved flags from Nuxt app context.

Testing

Current branch status:

• npm run lint passes.
• npm run test passes (208 tests).
• npx nuxt-module-build build passes (non-blocking builder warnings may appear).

Documentation

• Getting Started
• Features
• Context
• Variants
• API
• Validation

License

MIT License (c) 2024