You're viewing the docs for Flags 0.x. The latest is 1.x (rc). Go to the 1.x (rc) 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>