flagkit

v0.0.5

Published

7 months ago

Add feature flags to your Nuxt app

0High
0Medium
0Low

FlagKit

A powerful and flexible feature flags module for Nuxt 3 with TypeScript support, auto-imports, and rule-based evaluation.

⚠️ Early Development Stage! ⚠️
FlagKit is a new project and currently in its early stages of development. While I'm working to make it stable and feature-rich, please be aware that APIs might change, and you might encounter some rough edges.
Your contributions, feedback, and even forks to experiment are highly welcome and appreciated! Let's build something great together.

✨ Features

🚀 Simple API - Easy to use composables with excellent DX
🔧 Multiple Activation Methods - Static config, environment variables, and dynamic rules
📝 TypeScript Support - Full type safety with autocompletion for flag names
🎯 Flexible Rules - Path-based evaluation system for any context (user, team, subscription, etc.)
🔄 Reactive - Automatically updates when context changes
🌐 SSR/SSG Compatible - Works seamlessly with server-side rendering
🐛 Debug Mode - Detailed logging for development
🔌 Auto-imports - No manual imports needed

📦 Installation

You can auto-install the module with the following command:

npx nuxi module add flagkit

Or manually install it with your package manager of choice:

npm install flagkit
# or
pnpm add flagkit
# or
yarn add flagkit

Then add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['flagkit'],
})

🚀 Quick Start

Configure the module in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['flagkit'],
  
  flagkit: {
    debug: true, // Enable debug mode in development
    flags: {
      'new-dashboard': {
        enabled: true,
        description: 'Enable the new dashboard design'
      },
      'admin-panel': {
        enabled: false,
        description: 'Admin panel access',
        rules: [
          {
            path: 'user.role',
            operator: 'equals',
            value: 'admin'
          }
        ]
      }
    }
  }
})

Use in your components:

<template>
  <div>
    <!-- Simple reactive flag -->
    <NewDashboard v-if="isNewDashboardEnabled" />
    <OldDashboard v-else />
    
    <!-- Conditional admin panel -->
    <AdminPanel v-if="isAdminPanelEnabled" />
  </div>
</template>

<script setup>
// Individual flags with autocompletion
const isNewDashboardEnabled = useFeatureFlag('new-dashboard')
const isAdminPanelEnabled = useFeatureFlag('admin-panel')

// Full API access
const { isEnabled, updateContext } = useFeatureFlags()

// Update context when user changes (e.g., with nuxt-auth-utils)
const { data: user } = await useAuthUser()
watch(user, (newUser) => {
  updateContext({ user: newUser })
})
</script>

📖 Configuration

Basic Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  flagkit: {
    debug: true, // Enable debug logging
    flags: {
      'feature-name': {
        enabled: true,
        description: 'Description of the feature',
        envVar: 'FEATURE_NAME' // Environment variable override
      }
    }
  }
})

Environment Variable Overrides

You can override any flag using environment variables:

# .env
FEATURE_NEW_DASHBOARD=true
FEATURE_BETA=false

Flexible Rule-Based Evaluation

The rule system allows you to create dynamic feature flags based on any context:

flags: {
  'admin-features': {
    enabled: false,
    rules: [
      {
        path: 'user.role',
        operator: 'equals',
        value: 'admin'
      }
    ]
  },
  'team-features': {
    enabled: false,
    rules: [
      {
        path: 'team.plan',
        operator: 'in',
        value: ['premium', 'enterprise']
      }
    ]
  },
  'subscription-features': {
    enabled: false,
    rules: [
      {
        path: 'subscription.status',
        operator: 'equals',
        value: 'active'
      },
      {
        path: 'subscription.plan',
        operator: 'equals',
        value: 'pro'
      }
    ]
  },
  'email-domain-feature': {
    enabled: false,
    rules: [
      {
        path: 'user.email',
        operator: 'endsWith',
        value: '@company.com'
      }
    ]
  }
}

🎯 Rule System

Available Operators

equals - Exact match
contains - String contains substring
endsWith - String ends with substring
startsWith - String starts with substring
in - Value is in array
exists - Property exists and is not null/undefined
gt - Greater than (numeric)
lt - Less than (numeric)
gte - Greater than or equal (numeric)
lte - Less than or equal (numeric)
modulo - Modulo operation for percentage rollouts

Path-Based Evaluation

The path property uses dot notation to access nested properties in your context:

// Context
{
  user: {
    id: 123,
    email: '[email protected]',
    role: 'admin',
    profile: {
      subscription: {
        plan: 'pro',
        status: 'active'
      }
    }
  },
  team: {
    id: 456,
    plan: 'enterprise'
  }
}

// Rules
{
  path: 'user.role',              // → 'admin'
  path: 'user.profile.subscription.plan', // → 'pro'
  path: 'team.plan',              // → 'enterprise'
}

Multiple Rules (AND Logic)

When multiple rules are defined, ALL rules must pass for the flag to be enabled:

'premium-feature': {
  enabled: false,
  rules: [
    {
      path: 'subscription.status',
      operator: 'equals',
      value: 'active'
    },
    {
      path: 'subscription.plan',
      operator: 'in',
      value: ['pro', 'enterprise']
    }
  ]
}

🔧 API Reference

`useFeatureFlags()`

Main composable for feature flag management:

const { isEnabled, getFlags, updateContext, refresh } = useFeatureFlags()

// Check if a flag is enabled
const enabled = isEnabled('feature-name')

// Get all flags
const allFlags = getFlags()

// Update context (triggers re-evaluation)
updateContext({ 
  user: newUser,
  team: newTeam,
  subscription: newSubscription
})

// Manually refresh all flags
refresh()

`useFeatureFlag(flagName)`

Simple composable for individual flags:

// Returns a reactive boolean
const isEnabled = useFeatureFlag('feature-name')

// Use in template
<div v-if="isEnabled">Feature content</div>

🎨 Examples

Percentage Rollouts

'gradual-rollout': {
  enabled: false,
  rules: [
    {
      path: 'user.id',
      operator: 'modulo',
      value: { divisor: 100, remainder: 0 } // 1% of users
    }
  ]
}

A/B Testing

'variant-a': {
  enabled: false,
  rules: [
    {
      path: 'user.id',
      operator: 'modulo',
      value: { divisor: 2, remainder: 0 } // 50% of users
    }
  ]
},
'variant-b': {
  enabled: false,
  rules: [
    {
      path: 'user.id',
      operator: 'modulo',
      value: { divisor: 2, remainder: 1 } // Other 50% of users
    }
  ]
}

Complex Business Logic

'enterprise-feature': {
  enabled: false,
  rules: [
    {
      path: 'team.plan',
      operator: 'equals',
      value: 'enterprise'
    },
    {
      path: 'user.role',
      operator: 'in',
      value: ['admin', 'owner']
    },
    {
      path: 'subscription.status',
      operator: 'equals',
      value: 'active'
    }
  ]
}

Clone this repository
Install latest LTS version of Node.js
Enable Corepack using corepack enable
Install dependencies using pnpm install
Start development server using pnpm dev
Open http://localhost:3000 in your browser