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.
Creating Flags
Create flags in the console, or declare them in code — and keep them typed either way.
A flag has a declaration — key, type, default, owner — and targeting — who gets what. Targeting always lives in the database and is edited in the console. The declaration can live in either place.
In the console (the usual way)
Open the console, click New flag, and fill in:
| Field | What it is for |
|---|---|
| Key | What code reads: ctx.flags.enabled('holiday_banner') |
| Type | boolean, string (with named variants), number or json |
| Default | Served whenever nothing else answers, and to everyone until you add targeting |
| Variants | For string flags: the allowed values |
| Description, owner, tags | Shown and filterable in the console |
| Expires | After this date the flag is listed as stale |
| Send to the browser | Allows the value to reach the frontend (ctx.flags.all(), useFlag) |
The flag exists for every process the moment it is saved: the declaration travels with the ruleset, so the default is served without a deploy — on standalone apps and on tenants of a central server alike. Description, owner, expiry, tags and browser exposure stay editable in the flag's Details panel; the type is fixed once created.
Typing console flags
Code can read any key, but to get autocomplete and type checking for console flags, generate their types:
node ace flags:types # writes types/flags.d.tsCommit the file and rerun the command after creating flags. The generated file also turns on strict keys: from then on, a key that is neither declared in code nor generated is a compile error (--no-strict keeps accepting any string).
In code
Declare flags in config/flags.ts when a flag must exist before anyone opens the console, or when you want its type next to the code that reads it:
import { defineConfig, flag, type InferFlags } from '@adonis-agora/flags'
const flagsConfig = defineConfig({
flags: {
new_player: flag.boolean({ default: false, owner: 'video-team', expiresAt: '2027-03-31' }),
checkout: flag.string({ default: 'control', variants: ['control', 'one_page'] }),
max_uploads: flag.number({ default: 10 }),
pricing_banner: flag.json({ default: { text: '', color: 'blue' }, client: true }),
},
})
export default flagsConfig
declare module '@adonis-agora/flags/types' {
interface FlagsList extends InferFlags<typeof flagsConfig> {}
}Every builder accepts description, owner, expiresAt, tags and client.
When a key is declared in both places, code wins: the console shows it as declared in code and edits only its targeting.
Types are enforced on edits
Whichever way a flag was declared, the console and the commands refuse targeting that contradicts it — a string variant on a boolean flag, or a variant name outside the declared list — with the path of the offending field.