Installation

Azu runs inside your AdonisJS app, at /admin. You’ll add Bouncer, install Azu, and write one rule that says who gets in.

Requirements

• AdonisJS 7 with Lucid, Auth, and Bouncer.
• Inertia with React.
• Node.js 24.21 or later.
• PostgreSQL, MySQL, or SQLite.

The panel also needs Vite, Edge, an Inertia config and provider, and a session guard. Configure checks your app’s files before it makes changes. If it finds a Vite or Inertia config but can’t confirm its provider, it warns you and continues. See Ace commands for the checks.

Note: the React and Vue starter kits have everything but Bouncer. The Hypermedia kit needs two more steps, and the API kit isn’t supported yet. Starter kits has the details.

Install

1. Add Bouncer, if your app doesn’t have it. Azu’s access gate is a Bouncer ability, and the AdonisJS starter kits don’t include Bouncer.

   node ace add @adonisjs/bouncer

2. Install Azu and its React package with the preview tag, then configure Azu. Use pnpm add or yarn add if you prefer.

   npm i @mezielabs/azu@preview @mezielabs/azu-react@preview
   node ace configure @mezielabs/azu

   The @preview tag goes away at 0.1.0. From then on, node ace add @mezielabs/azu installs and configures in one step.

3. Decide who gets in. Configuring adds an accessAdmin ability to app/abilities/main.ts that returns false, so nothing is exposed until you change it.

What configure does

Configuring Azu:

• registers its provider and creates config/azu.ts.
• mounts the panel at /admin.
• adds a separate Vite entry, so your public pages never load admin code.
• adds the accessAdmin ability to app/abilities/main.ts.

Let people in

accessAdmin decides who can open the panel. The demo store lets in admins and staff:

app/abilities/main.ts

export const accessAdmin = Bouncer.ability((user: User) => {
  return user.role === 'admin' || user.role === 'staff'
})

On a fresh starter kit, allow your email while you try Azu locally. Add the User import and replace the generated accessAdmin ability:

app/abilities/main.ts

import type User from '#models/user'

export const accessAdmin = Bouncer.ability((user: User) => {
  return user.email === 'you@example.com'
})

Caution

Before deploying, use a rule tied to a trusted account or role. With public signup, someone else can register an allowlisted email unless your app verifies ownership.

Note: if you added Azu before Bouncer, run node ace add @adonisjs/bouncer, then node ace configure @mezielabs/azu again to add the ability. Without Bouncer, Azu denies everyone.

Signing in

Azu uses your app’s existing auth guard. Guests are sent to your login page, and signed-in users who fail accessAdmin get a 403.

With session middleware, Azu remembers the admin page a guest asked for. Your login can send them back there. Troubleshooting shows the demo’s login controller.

Next

Quick start generates your first resource.