Feature Flags
Deterministic runtime feature toggles with percentage rollout, tenant and user allow-lists, and scheduled activation windows.
On this page10
Overview
The feature flag system provides runtime feature toggles with deterministic, identity-based rollout using FNV-1a hashing. The same identity always gets the same result across requests and server instances, with no random flipping.
Basic Usage
1import { featureFlags } from '@axiljs/cloud'
2
3featureFlags.define({
4 name: 'new-checkout',
5 enabled: true,
6 rolloutPercentage: 25,
7})
8
9const enabled = featureFlags.isEnabled('new-checkout', {
10 userId: 'usr-42',
11})define() creates or replaces a flag. rolloutPercentage defaults to 100 and
must be an integer from 0 to 100; anything else throws a RangeError.
Deterministic Rollout
AxilJS hashes the flag name together with an identity to place each caller in a
bucket from 0 to 99. The caller gets the flag when its bucket is below
rolloutPercentage. The identity is userId, falling back to tenantId, then
to 'anonymous'.
- The same identity always gets the same answer for a given flag
- No UI flickering between requests
- Consistent behaviour across horizontally scaled instances
1featureFlags.define({
2 name: 'beta-dashboard',
3 enabled: true,
4 rolloutPercentage: 50,
5})
6
7featureFlags.isEnabled('beta-dashboard', { userId: 'usr-100' }) // same result...
8featureFlags.isEnabled('beta-dashboard', { userId: 'usr-100' }) // ...every timeTenant and User Allow-Lists
allowedTenants and allowedUsers are allow-lists. A caller that matches either
list gets the flag regardless of rolloutPercentage. When a list is non-empty,
callers that match neither list are rejected, even at 100% rollout.
1featureFlags.define({
2 name: 'premium-reports',
3 enabled: true,
4 allowedTenants: ['acme-corp'],
5 allowedUsers: ['vip-user-1'],
6})
7
8featureFlags.isEnabled('premium-reports', { tenantId: 'acme-corp' }) // true
9featureFlags.isEnabled('premium-reports', { tenantId: 'other', userId: 'vip-user-1' }) // true
10featureFlags.isEnabled('premium-reports', { tenantId: 'other' }) // falseWarning
Empty allow-lists mean "no allow-list", not "nobody". allowedTenants: []
and allowedUsers: [] behave exactly like omitting the property: every tenant
and user is evaluated against rolloutPercentage. To turn a flag off for
everyone, set enabled: false.
1// Wrong: this does NOT disable the flag; all tenants still get it
2featureFlags.define({ name: 'legacy-export', enabled: true, allowedTenants: [] })
3
4// Right: switch the flag off
5featureFlags.define({ name: 'legacy-export', enabled: false })Scheduled Activation
Flags can be scheduled to activate and expire automatically. Outside the window
isEnabled() returns false, including for allow-listed callers.
1featureFlags.define({
2 name: 'holiday-promo',
3 enabled: true,
4 startAt: '2026-12-01T00:00:00Z',
5 endAt: '2026-12-31T23:59:59Z',
6})Custom Manager Instance
featureFlags is a shared in-memory FeatureFlagManager. For isolated flag
scopes or tests, create your own.
1import { FeatureFlagManager } from '@axiljs/cloud'
2
3const myFlags = new FeatureFlagManager()
4myFlags.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; false disables for everyone |
description | string | — | Optional human-readable note |
rolloutPercentage | number (integer 0–100) | 100 | Deterministic rollout bucket |
allowedTenants | string[] | — | Tenant allow-list; empty array = no allow-list |
allowedUsers | (string | number)[] | — | User allow-list; empty array = no allow-list |
startAt | string (ISO 8601) | — | Flag is inactive before this time |
endAt | string (ISO 8601) | — | Flag is inactive after this time |
isEnabled(name, context?)
context is { tenantId?: string; userId?: string | number }. Returns
boolean; unknown flags return false.
Evaluation order:
- Enabled: a missing flag or
enabled: falsereturnsfalse. - Schedule: before
startAtor afterendAtreturnsfalse. - Allow-lists: a match in a non-empty
allowedTenantsorallowedUsersreturnstrue. If either list is non-empty and nothing matched, returnsfalse. - Rollout: below 100%, the identity bucket must be under
rolloutPercentage.
get(name) / getAll() / remove(name)
get returns the FeatureFlag or undefined, getAll returns FeatureFlag[],
and remove returns true if a flag was deleted.
Was this page helpful?