Validation & Build Checks

The module includes built-in validation to catch configuration errors and undeclared flag usage.

Automatic Runtime Validation

Flag Naming Rules

All flag and variant names must follow these rules:

• Must start with a letter (a-z, A-Z)
• Can contain: letters, numbers, hyphens (-), underscores (_)
• Maximum length: 50 characters

Valid Examples:

{
  newFeature: true,              // ✅ Valid
  feature_v2: true,              // ✅ Valid
  my-feature-123: true,          // ✅ Valid
  experimentalDashboard: true    // ✅ Valid
}

Invalid Examples:

{
  '123feature': true,            // ❌ Starts with number
  'feature!': true,              // ❌ Contains invalid character
  'my feature': true,            // ❌ Contains space
}

Variant Validation Rules

Variants must follow these rules:

• Weights must be 0-100: Each variant weight must be between 0 and 100
• Total weights cannot exceed 100: Sum of all variant weights must be ≤ 100
• No duplicate variant names: Each variant must have a unique name

Valid Examples:

{
  experiment: {
    enabled: true,
    variants: [
      { name: 'control', weight: 50 },
      { name: 'treatment', weight: 50 }     // ✅ Total: 100
    ]
  }
}

Invalid Examples:

{
  badWeights: {
    enabled: true,
    variants: [
      { name: 'a', weight: 60 },
      { name: 'b', weight: 50 }             // ❌ Total: 110%
    ]
  }
}

Build-Time Validation

Using validateFeatureFlags

// scripts/validate-flags.ts
import { validateFeatureFlags } from 'nuxt-feature-flags/build'

const errors = await validateFeatureFlags({
  configPath: './feature-flags.config.ts',
  srcPatterns: [
    '**/*.vue',
    '**/*.ts',
    '**/*.js',
    'server/**/*.ts'
  ],
  failOnErrors: true
})

if (errors.length > 0) {
  console.error('Feature flag validation failed:')
  errors.forEach(error => console.error(`  - ${error}`))
  process.exit(1)
}

What is Checked

1. Undeclared Flags: Flags used in code but not defined in configuration
2. Invalid Configurations: Flags with validation errors (naming, weights, etc.)
3. Unreferenced Flags: Flags defined in config but never used in code
4. Typos in Flag Names: Similar flag names that might be typos

Example Validation Output

$ npm run validate:flags

Validating feature flags...

✓ Found 15 flags in configuration
✓ Scanned 47 files

Errors:
  ✗ Undeclared flag 'experimentalFeatur' used in src/components/Dashboard.vue:23
    Did you mean 'experimentalFeature'?
  ✗ Invalid flag name 'new-feature!' in configuration
  ✗ Variant weights exceed 100% for flag 'abTest' (total: 110%)

Warnings:
  ⚠ Flag 'oldFeature' is declared but never used
  ⚠ Flag 'deprecatedFlag' is declared but never used

CI/CD Integration

GitHub Actions Example

# .github/workflows/validate-flags.yml
name: Validate Feature Flags

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main, develop]

jobs:
  validate:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Validate feature flags
        run: npm run validate:flags

Package.json Script Integration

{
  "scripts": {
    "validate:flags": "tsx scripts/validate-flags.ts",
    "build": "npm run validate:flags && nuxt build",
    "test": "npm run validate:flags && vitest run"
  }
}

Pre-commit Hook Example

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo "Validating feature flags..."
npm run validate:flags || {
  echo "❌ Feature flag validation failed. Please fix the errors before committing."
  exit 1
}