Feature Flags | AxilJS Docs

Overview

The feature flag system provides runtime feature toggles with deterministic, identity-based rollout using FNV-1a hashing. The same user always gets the same result across requests and server instances — no random flipping.

Basic Usage

typescript

import { featureFlags } from '@axiljs/cloud'
 
featureFlags.define({
  name: 'new-checkout',
  enabled: true,
  rolloutPercentage: 25,
})
 
const enabled = featureFlags.isEnabled('new-checkout', {
  userId: 'usr-42',
})

Deterministic Rollout

Unlike random percentage rollouts, AxilJS uses a stable hash of the flag name and user identity to assign users to buckets. This means:

User A always sees the feature ON (or OFF)
No UI flickering between requests
Consistent behaviour across horizontally scaled instances

typescript

featureFlags.define({
  name: 'beta-dashboard',
  enabled: true,
  rolloutPercentage: 50,
})
 
featureFlags.isEnabled('beta-dashboard', { userId: 'usr-100' }) // true
featureFlags.isEnabled('beta-dashboard', { userId: 'usr-100' }) // true

Tenant and User Targeting

Whitelisted tenants and users bypass the rollout percentage entirely.

typescript

featureFlags.define({
  name: 'premium-reports',
  enabled: true,
  rolloutPercentage: 0,
  allowedTenants: ['acme-corp'],
  allowedUsers: ['vip-user-1'],
})
 
featureFlags.isEnabled('premium-reports', { tenantId: 'acme-corp' }) // true
featureFlags.isEnabled('premium-reports', { tenantId: 'other' })     // false

Scheduled Activation

Flags can be scheduled to activate and expire automatically.

typescript

featureFlags.define({
  name: 'holiday-promo',
  enabled: true,
  rolloutPercentage: 100,
  startAt: '2025-12-01T00:00:00Z',
  endAt: '2025-12-31T23:59:59Z',
})

Custom Manager Instance

For isolated flag scopes or testing, create a separate manager.

typescript

import { FeatureFlagManager } from '@axiljs/cloud'
 
const myFlags = new FeatureFlagManager()
myFlags.define({ name: 'experiment-1', enabled: true, rolloutPercentage: 10 })

API Reference

`define(flag)`

Property	Type	Default	Description
`name`	`string`	—	Unique flag identifier
`enabled`	`boolean`	—	Global on/off switch
`rolloutPercentage`	`number` (0–100)	`100`	Deterministic rollout bucket
`allowedTenants`	`string[]`	—	Tenant whitelist (bypasses %)
`allowedUsers`	`(string \| number)[]`	—	User whitelist (bypasses %)
`startAt`	`string` (ISO 8601)	—	Activation date
`endAt`	`string` (ISO 8601)	—	Expiration date

`isEnabled(name, context?)`

Returns boolean. Evaluation order: enabled → schedule → tenant list → user list → rollout hash.

`get(name)` / `getAll()` / `remove(name)`

Retrieve or delete flag definitions.