Agora

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

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 →