AdonisJS Fanion 🏁

AdonisJS adapter for the Fanion feature flagging library

AdonisJS Fanion is the official AdonisJS adapter for the Fanion feature flagging library. It provides a seamless integration with AdonisJS applications, allowing you to control feature rollouts, conduct A/B tests, and manage application behavior dynamically.

Features

🚀 AdonisJS Native - Built specifically for AdonisJS v6 with full IoC support
🔧 TypeScript First - Complete type safety and IntelliSense support
🏪 Multiple Storage Options - Memory, database, or custom storage providers
🎯 Context-Aware - Automatic HTTP context integration
🛡️ Middleware Support - Protect routes with feature flags
🎨 Decorators - Use decorators in controllers for feature gating
📊 A/B Testing - Built-in utilities for A/B testing and gradual rollouts
🌍 Environment Support - Environment-based feature flags

Installation

npm i @mgvdev/fanion-adonisjs

Next, configure the package using the configure command:

node ace configure @mgvdev/fanion-adonisjs

This will:

Create a config/fanion.ts configuration file
Register the service provider
Set up environment variables
Optionally install database drivers

Quick Start

Basic Usage

// Define feature flags in config/fanion.ts
export default defineConfig({
  features: [
    {
      name: 'new-dashboard',
      description: 'Enable new dashboard design',
      check: () => true,
    },
    {
      name: 'beta-features',
      description: 'Enable beta features for specific users',
      check: (context) => context.user?.isBetaUser === true,
    },
  ],
})

// Use in controllers
import { inject } from '@adonisjs/core'
import type { HttpContext } from '@adonisjs/core/http'
import type { FanionService } from '@fanion/adonisjs/types'

export default class DashboardController {
  @inject()
  async index({ response, auth }: HttpContext, fanion: FanionService) {
    const showNewDashboard = await fanion.activeForRequest('new-dashboard', { auth })

    if (showNewDashboard) {
      return response.ok({ message: 'New dashboard!' })
    }

    return response.ok({ message: 'Classic dashboard' })
  }
}

Using Middleware

// routes/web.ts
import router from '@adonisjs/core/services/router'
import { featureFlag } from '@fanion/adonisjs'

// Protect entire route
router.get('/beta', [featureFlag('beta-features')]).use(async ({ response }) => {
  return response.ok({ message: 'Beta feature accessed!' })
})

// Redirect when disabled
router.get('/new-ui', [featureFlagWithRedirect('new-ui', '/old-ui')]).use(async ({ response }) => {
  return response.ok({ message: 'New UI!' })
})

Using Decorators

import { requireFeature } from '@fanion/adonisjs'

export default class AdminController {
  @requireFeature('admin-panel')
  async index({ response }: HttpContext) {
    return response.ok({ message: 'Admin panel' })
  }

  @requireFeature('super-admin', {
    onDisabled: 'redirect',
    redirectTo: '/dashboard',
  })
  async users({ response }: HttpContext) {
    return response.ok({ users: [] })
  }
}

Configuration

Basic Configuration

// config/fanion.ts
import { defineConfig } from '@fanion/adonisjs/types'
import env from '#start/env'

export default defineConfig({
  // Enable debug logging
  debug: env.get('NODE_ENV') === 'development',

  // Auto-initialize storage on app start
  autoInit: true,

  // Default context provider
  defaultContextProvider: () => ({
    environment: env.get('NODE_ENV'),
    appVersion: env.get('APP_VERSION', '1.0.0'),
  }),
})

Database Storage

// config/fanion.ts
import { defineConfig } from '@fanion/adonisjs/types'
import db from '@adonisjs/lucid/services/db'

export default defineConfig({
  storageDriver: {
    type: 'knex',
    config: {
      connection: db.connection(),
      tableName: 'feature_flags',
      featureNameColumn: 'feature_name',
      valueColumn: 'value',
    },
  },
})

Feature Flag Definitions

// config/fanion.ts
export default defineConfig({
  features: [
    // Simple boolean flag (stored in database)
    {
      name: 'maintenance-mode',
      description: 'Enable maintenance mode',
      store: true,
      defaultValue: false,
    },

    // User-based flag
    {
      name: 'premium-features',
      description: 'Enable premium features',
      check: (context) => {
        return context.user?.plan === 'premium' && context.user?.verified
      },
    },

    // Percentage-based rollout
    {
      name: 'new-feature',
      description: 'Roll out new feature to 25% of users',
      check: (context) => {
        const userId = context.user?.id || 0
        return userId % 100 < 25
      },
    },

    // Environment-based flag
    {
      name: 'debug-mode',
      description: 'Enable debug mode in development',
      check: () => process.env.NODE_ENV === 'development',
    },
  ],
})

Advanced Usage

A/B Testing

import { ABTesting } from '@fanion/adonisjs'

// In config/fanion.ts
export default defineConfig({
  features: [
    {
      name: 'checkout-variant-a',
      description: 'A/B test for checkout flow - Variant A',
      check: ABTesting.createABTest('checkout', 50, (ctx) => ctx.user?.id || 0),
    },
  ],
})

// In your controller
export default class CheckoutController {
  @inject()
  async show({ response }: HttpContext, fanion: FanionService) {
    const showVariantA = await fanion.active('checkout-variant-a', { user: auth.user })

    return response.ok({
      variant: showVariantA ? 'A' : 'B',
      checkoutFlow: showVariantA ? 'simplified' : 'standard',
    })
  }
}

Custom Context

// Create custom context for feature evaluation
import { createFeatureContext } from '@fanion/adonisjs'

export default class ApiController {
  @inject()
  async data({ request, auth }: HttpContext, fanion: FanionService) {
    const context = createFeatureContext(
      { auth },
      {
        apiVersion: request.header('api-version'),
        clientType: request.header('client-type'),
        country: request.header('cf-ipcountry'), // Cloudflare country header
      }
    )

    const features = await fanion.activeMany(
      ['enhanced-api', 'geo-restrictions', 'rate-limiting'],
      context
    )

    return response.ok({ features })
  }
}

Environment-Based Flags

import { EnvironmentFlags } from '@fanion/adonisjs'

export default defineConfig({
  features: [
    {
      name: 'dev-tools',
      check: EnvironmentFlags.developmentOnly(),
    },
    {
      name: 'analytics',
      check: EnvironmentFlags.productionOnly(),
    },
    {
      name: 'staging-banner',
      check: EnvironmentFlags.createEnvironmentFlag(['staging', 'development']),
    },
  ],
})

Multiple Flag Checks

export default class DashboardController {
  @inject()
  async index({ auth }: HttpContext, fanion: FanionService) {
    const flags = await fanion.activeMany(
      ['new-dashboard', 'advanced-analytics', 'export-feature', 'real-time-updates'],
      { user: auth.user }
    )

    return response.ok({
      dashboard: {
        showNewDesign: flags['new-dashboard'],
        showAnalytics: flags['advanced-analytics'],
        allowExport: flags['export-feature'],
        realTimeUpdates: flags['real-time-updates'],
      },
    })
  }
}

Middleware Options

Basic Middleware

import { featureFlag, featureFlagWithRedirect, featureFlagWithHandler } from '@fanion/adonisjs'

// Simple abort on disabled
router.get('/feature', [featureFlag('my-feature')])

// Redirect when disabled
router.get('/feature', [featureFlagWithRedirect('my-feature', '/coming-soon')])

// Custom handler when disabled
router.get('/feature', [
  featureFlagWithHandler('my-feature', ({ response }) => {
    return response.status(503).json({ message: 'Feature temporarily unavailable' })
  }),
])

Advanced Middleware

import { createFanionMiddleware } from '@fanion/adonisjs'

// Custom middleware with context provider
const betaMiddleware = createFanionMiddleware({
  flag: 'beta-features',
  contextProvider: async ({ auth, request }) => ({
    user: auth.user,
    userAgent: request.header('user-agent'),
    isMobile: request.header('user-agent')?.includes('Mobile'),
  }),
  onDisabled: 'custom',
  customHandler: ({ response }) => {
    return response.status(404).json({
      error: 'Feature not found',
      message: 'This feature is not available in your current plan',
    })
  },
})

router.get('/beta', [betaMiddleware])

Helpers and Utilities

Global Helpers

import { isFeatureActive, getUserFeatures, ifFeatureActive } from '@fanion/adonisjs'

// Check feature globally
const isEnabled = await isFeatureActive('my-feature')

// Get all features for a user
const userFeatures = await getUserFeatures(user, ['feature1', 'feature2'])

// Conditional execution
await ifFeatureActive('email-notifications', async () => {
  await sendWelcomeEmail(user)
})

View Helpers

// In a service provider or preloader
import { ViewHelpers } from '@fanion/adonisjs'

export default class AppProvider {
  async boot() {
    const fanion = await this.app.container.make('fanion')
    const view = await this.app.container.make('view')

    // Add global view helpers
    view.global(ViewHelpers.createViewGlobals(fanion))
  }
}

{{-- In your Edge templates --}}
@if(await isFeatureActive('new-ui'))
  <div class="new-ui-component">
    <!-- New UI content -->
  </div>
@else
  <div class="legacy-ui-component">
    <!-- Legacy UI content -->
  </div>
@end

Database Schema

When using database storage, the following table structure is created:

CREATE TABLE feature_flags (
  feature_name VARCHAR PRIMARY KEY,
  value BOOLEAN NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

You can customize the table name and column names in the configuration:

export default defineConfig({
  storageDriver: {
    type: 'knex',
    config: {
      connection: db.connection(),
      tableName: 'app_feature_flags',
      featureNameColumn: 'flag_name',
      valueColumn: 'is_enabled',
    },
  },
})

Best Practices

1. Use Descriptive Names

// Good
'user-profile-redesign'
'checkout-express-shipping'
'admin-advanced-analytics'

// Avoid
'flag1'
'test'
'new-feature'

2. Document Your Flags

export default defineConfig({
  features: [
    {
      name: 'payment-method-apple-pay',
      description: 'Enable Apple Pay as payment method in checkout',
      check: (context) => {
        // Only enable for iOS users
        return context.userAgent?.includes('iPhone') || context.userAgent?.includes('iPad')
      },
    },
  ],
})

3. Use Kill Switches for Risky Features

// Store critical features in database for quick toggles
{
  name: 'payment-processing',
  description: 'Kill switch for payment processing',
  store: true,
  defaultValue: true,
}

4. Implement Gradual Rollouts

{
  name: 'new-search-algorithm',
  description: 'Gradual rollout of new search algorithm',
  check: (context) => {
    const userId = context.user?.id || 0
    const rolloutPercentage = 10 // Start with 10%
    return (userId % 100) < rolloutPercentage
  },
}

5. Handle Errors Gracefully

export default class FeatureController {
  @inject()
  async show({ response }: HttpContext, fanion: FanionService) {
    try {
      const isActive = await fanion.active('experimental-feature')
      // Use feature
    } catch (error) {
      // Log error and fall back to safe default
      console.error('Feature flag error:', error)
      // Provide fallback behavior
    }
  }
}

Testing

Testing Feature Flags

// tests/functional/feature_flags.spec.ts
import { test } from '@japa/runner'
import { FanionServiceImpl } from '@fanion/adonisjs'

test.group('Feature Flags', () => {
  test('should enable premium features for premium users', async ({ assert }) => {
    const fanion = new FanionServiceImpl()

    fanion.define('premium-features', (context) => {
      return context.user?.plan === 'premium'
    })

    const result = await fanion.active('premium-features', {
      user: { plan: 'premium' },
    })

    assert.isTrue(result)
  })
})

Testing with Middleware

test('should protect routes with feature flags', async ({ client }) => {
  const response = await client.get('/beta-feature')

  // Should return 404 if feature is disabled
  response.assertStatus(404)
})

Migration Guide

From Manual Feature Flags

If you're currently using manual feature flag implementations:

// Before
if (process.env.ENABLE_NEW_FEATURE === 'true') {
  // Feature logic
}

// After
if (await fanion.active('new-feature')) {
  // Feature logic
}

From Other Feature Flag Libraries

Most feature flag libraries can be migrated by:

Defining your existing flags in config/fanion.ts
Replacing flag checks with fanion.active()
Updating middleware to use Fanion middleware
Migrating stored flags to your database

Troubleshooting

Common Issues

Feature flag not found error

FeatureNotExistsError: Feature flag 'my-feature' is not defined

Solution: Make sure the feature is defined in your configuration or via fanion.define().

Storage provider not initialized

Error: No store provider defined

Solution: Configure a storage driver in your configuration or set autoInit: true.

Middleware not working

Error: Binding not found: fanion

Solution: Make sure the FanionProvider is registered in your adonisrc.ts providers array.

Debug Mode

Enable debug mode to see detailed logging:

export default defineConfig({
  debug: true,
})

This will log all feature flag evaluations to help with debugging.

API Reference

FanionService

define<T>(name: string, check?: (context: T) => boolean | Promise<boolean>): void
defineAndStore(name: string, defaultValue?: boolean): Promise<void>
active<T>(name: string, context?: T): Promise<boolean>
activeForRequest(name: string, ctx: HttpContext, additionalContext?: any): Promise<boolean>
activeMany<T>(flags: string[], context?: T): Promise<Record<string, boolean>>
getDefinedFlags(): string[]

Middleware

featureFlag(flagName: string, onDisabled?: 'abort' | 'next')
featureFlagWithRedirect(flagName: string, redirectTo: string)
featureFlagWithHandler(flagName: string, customHandler: Function)
createFanionMiddleware(options: FanionMiddlewareOptions)

Helpers

isFeatureActive<T>(flagName: string, context?: T): Promise<boolean>
isFeatureActiveForRequest(flagName: string, ctx: HttpContext, additionalContext?: any): Promise<boolean>
getUserFeatures(user: any, flagNames?: string[]): Promise<Record<string, boolean>>
ifFeatureActive<T>(flagName: string, callback: Function, context?: T): Promise<any>
requireFeature(flagName: string, options?: object): MethodDecorator

Utilities

ABTesting.createABTest(testName: string, percentage: number, identifier?: Function)
ABTesting.percentageRollout(identifier: number | string, percentage: number): boolean
EnvironmentFlags.developmentOnly(): () => boolean
EnvironmentFlags.productionOnly(): () => boolean
EnvironmentFlags.createEnvironmentFlag(environments: string[]): () => boolean

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github		.github
bin		bin
providers		providers
src		src
stubs		stubs
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
LICENSE.md		LICENSE.md
README.md		README.md
configure.ts		configure.ts
eslint.config.js		eslint.config.js
index.ts		index.ts
package.json		package.json
tsconfig.json		tsconfig.json
tsnode.esm.js		tsnode.esm.js

License

mgvdev/fanion-adonisjs

Folders and files

Latest commit

History

Repository files navigation

AdonisJS Fanion 🏁

Features

Installation

Quick Start

Basic Usage

Using Middleware

Using Decorators

Configuration

Basic Configuration

Database Storage

Feature Flag Definitions

Advanced Usage

A/B Testing

Custom Context

Environment-Based Flags

Multiple Flag Checks

Middleware Options

Basic Middleware

Advanced Middleware

Helpers and Utilities

Global Helpers

View Helpers

Database Schema

Best Practices

1. Use Descriptive Names

2. Document Your Flags

3. Use Kill Switches for Risky Features

4. Implement Gradual Rollouts

5. Handle Errors Gracefully

Testing

Testing Feature Flags

Testing with Middleware

Migration Guide

From Manual Feature Flags

From Other Feature Flag Libraries

Troubleshooting

Common Issues

Debug Mode

API Reference

FanionService

Middleware

Helpers

Utilities

Contributing

License

Related

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages