Agora

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/flags

The 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/lucid configured (Postgres, MySQL or SQLite). Without Lucid flags live in memory and reset on restart.

Install

node ace add @adonis-agora/flags

configure:

  1. registers the providers (flags and the console) and the flags:* commands in adonisrc.ts;
  2. adds the flags_middleware to the router middleware (it puts ctx.flags on every request) and the flag named middleware (a route guard);
  3. publishes config/flags.ts, config/flags_dashboard.ts (the console) and an optional migration;
  4. adds FLAGS_ENVIRONMENT to start/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).

database/migrations/1763600000000_update_flags_tables.ts
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):

config/flags.ts
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

app/controllers/player_controller.ts
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 says

Every 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:

config/flags.ts
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.

On this page

Partner

Your product as the official integration for Flags, right here.

Become a partner →