Flags 1.x is a release candidate. npm's latest tag still installs 0.x, so install these docs' version from the rc tag:
npm i @adonis-agora/flags@rc
node ace configure @adonis-agora/flagsThe same goes for every @adonis-agora/* package these docs install: add @rc, and where a page says node ace add, install with @rc first and then run node ace configure. On 0.x? Read the 0.x docs.
Reading Flags
ctx.flags in HTTP, the service elsewhere, evaluation details, route guards and Edge templates.
In a request: ctx.flags
async index({ flags }: HttpContext) {
await flags.enabled('new_player') // boolean flags
await flags.value('max_uploads') // the typed value
await flags.variant('checkout') // the variant name
await flags.details('checkout') // value, variant, reason, error
}Values are memoized for the request: a flag cannot change halfway through rendering a page.
The subject is the signed-in user. With @adonis-agora/authkit-client that is the authkit identity, with no configuration, and its claims become targeting attributes:
| Attribute | From |
|---|---|
targetingKey | the sub claim: the same person in every app |
email, emailDomain | the email claim |
globalRoles | authkit global roles (in matches any) |
orgId, orgSlug, orgRole | the session's active organization |
So "everyone in organization acme" or "users with the BETA role" are plain rules, and a rollout split by orgId gives a whole organization the same variant. Without authkit, ctx.auth.user is used. Authentication covers @adonisjs/auth, Bouncer and writing your own identity provider.
To use something else — an organization, an anonymous id — set subject in the config:
export default defineConfig({
flags: { /* … */ },
subject: (ctx) => ctx.auth.user ?? { id: ctx.request.cookie('anon_id'), type: 'anonymous' },
// Targeting attributes for every subject. Read them from your own data, never from the request.
attributes: async (subject) => {
const user = await User.find(subject.id)
return { plan: user?.plan, country: user?.country, orgId: user?.organizationId }
},
})Anywhere else: the service
import flags from '@adonis-agora/flags/services/main'
await flags.for(user).enabled('new_player')
await flags.for({ id: org.id, type: 'organization', attributes: { plan: org.plan } }).value('max_uploads')flags.for() takes a model with an id, an id, or { id, type, attributes }.
Why did I get this value?
const details = await ctx.flags.details('checkout')
// {
// flagKey: 'checkout',
// value: 'one_page',
// variant: 'one_page',
// reason: 'TARGETING_MATCH', // STATIC, DEFAULT, TARGETING_MATCH, SPLIT, DISABLED, ERROR
// flagMetadata: { ruleId: 'pro-users', rulesetVersion: '42' },
// }A flag declared in code but not configured yet serves its default with reason: 'DEFAULT' and flagMetadata.configured: false: the normal state of a new flag, not an error.
A failure never throws. It returns the code default with reason: 'ERROR' and an errorCode (FLAG_NOT_FOUND for a key nobody declared, PARSE_ERROR, TYPE_MISMATCH, TARGETING_KEY_MISSING). These names are OpenFeature's.
Route guard
import { middleware } from '#start/kernel'
router
.get('/checkout/new', [NewCheckoutController])
.use(middleware.flag({ flag: 'new_checkout' }))
router
.get('/checkout/one-page', [OnePageController])
.use(middleware.flag({ flag: 'checkout', variants: ['one_page'] }))When the flag says no, the route answers 404, as if it did not exist. Change it with status.
Edge templates
@flag('new_player')
@include('partials/new_player')
@else
@include('partials/classic_player')
@end
{{-- multivariate: any of the listed variants --}}
@flag('checkout', 'one_page')
@include('partials/one_page_checkout')
@endThe middleware also shares the request's flags as flags, for anything else:
<p>Up to {{ await flags.value('max_uploads') }} files.</p>