You're viewing the docs for Flags 0.x. The latest is 1.x (rc). Go to the 1.x (rc) docs
Getting Started
Install @adonis-agora/flags, declare a flag, read it in a controller and turn it on.
Prerequisites
- Node.js 24+
- AdonisJS 7
@adonisjs/lucidconfigured (Postgres, MySQL or SQLite). Without Lucid flags live in memory and reset on restart.
Install
node ace add @adonis-agora/flagsconfigure:
- registers the providers (flags and the console) and the
flags:*commands inadonisrc.ts; - adds the
flags_middlewareto the router middleware (it putsctx.flagson every request) and theflagnamed middleware (a route guard); - publishes
config/flags.ts,config/flags_dashboard.ts(the console) and an optional migration; - adds
FLAGS_ENVIRONMENTtostart/env.ts.
The tables are created at boot. If you prefer migrations to own the schema, keep the published migration and set autoCreateSchema: false.
To keep them out of your own tables, put them in a schema of their own (Postgres; on MySQL, a database):
export default defineConfig({
flags: { /* … */ },
schema: 'flags',
})The schema is created at boot if missing, and every query names it (flags.flags_events), so nothing depends on the connection's search_path: it works behind PgBouncer in transaction mode (see below for instant updates there). Events you track inside your own transaction ({ client: trx }) land there too. Not available on SQLite. Set it before the first boot: tables created elsewhere are not moved.
Create a flag
Open the console at /flags, click New flag, and give it a key, a type and a default — say new_player, boolean, false. It exists for every process as soon as it is saved. Creating flags covers the fields, typing console flags with node ace flags:types, and declaring flags in config/flags.ts instead.
Read it
import type { HttpContext } from '@adonisjs/core/http'
export default class PlayerController {
async show({ flags, inertia }: HttpContext) {
const component = (await flags.enabled('new_player')) ? 'player/new' : 'player/classic'
return inertia.render(component)
}
}ctx.flags evaluates for the signed-in user (the authkit identity, or ctx.auth.user). Outside HTTP, use the service:
import flags from '@adonis-agora/flags/services/main'
if (await flags.for(user).enabled('new_player')) {
// …
}Turn it on
In the console, open the flag and set a rollout, a rule, or serve on to everyone. From a terminal:
node ace flags:set new_player 10% # 10% of users
node ace flags:set new_player on # everyone
node ace flags:set new_player kill # kill switch: off for everyone, whatever the targeting saysEvery process picks the change up within seconds (immediately on Postgres, through LISTEN/NOTIFY).
Behind PgBouncer in transaction mode, LISTEN cannot work (the session it lives on is shared), so turn it off and let processes poll; the process that made the change still applies it at once:
refresh: { notify: false, intervalMs: 5000 },Until a flag is configured, it serves the default you declared. The same happens if the database is unreachable at boot: nothing throws, the code default is served.