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.
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.
With autoCreateSchema: false, an upgrade that adds columns needs a migration of its own. createFlagsTables adds whatever an existing table lacks (as NULL-able columns, without rewriting the table), so a new migration calling it is enough. node ace agora:doctor lists missing columns (flags.schema-columns).
import { BaseSchema } from '@adonisjs/lucid/schema'
import { createFlagsTables } from '@adonis-agora/flags'
export default class extends BaseSchema {
async up() {
this.defer(async (db) => {
await createFlagsTables(db as never /* , { schema: 'flags' } */)
})
}
}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.