Getting Started

Configuration

Every option available in config/permissions.ts.

The configuration lives in config/permissions.ts and is created with defineConfig:

config/permissions.ts

import { defineConfig } from '@eienjs/adonisjs-permission'

export default defineConfig({
  models: {
    role: () => import('#models/role'),
    permission: () => import('#models/permission'),
  },
  morphMap: {
    user: () => import('#models/user'),
  },
  defaultGuard: 'web',
  teams: false,
  enableWildcardPermission: false,
  superAdmin: { enabled: false, role: 'Super-Admin' },
  events: { enabled: false },
  cache: { enabled: true, key: 'adonisjs_permission_cache', ttl: '24h' },
  catalog: { permissions: [], roles: {} },
})

Options

Option	Default	Description
`models.role` / `models.permission`	required	Lazy loaders returning your Role and Permission models.
`morphMap`	`{}`	Alias → model loader. Aliases are stored in `model_type` instead of the table/class name.
`defaultGuard`	`'web'`	Guard used when none is given.
`teams`	`false`	Enables team scoping. See Teams.
`teamForeignKey`	`'team_id'`	Team column name.
`enableWildcardPermission`	`false`	See Wildcard permissions.
`superAdmin.enabled` / `superAdmin.role`	`false` / `'Super-Admin'`	See Super-Admin.
`events.enabled`	`false`	Emit events when roles/permissions change.
`cache.enabled` / `cache.key` / `cache.ttl`	`true` / `'adonisjs_permission_cache'` / `'24h'`	In-memory permission cache.
`catalog`	empty	Declarative roles and permissions. See Catalog.
`tableNames`	see below	Override table names.
`columnNames`	see below	Override column names.

Custom table and column names

defineConfig({
  // ...
  tableNames: {
    roles: 'roles',
    permissions: 'permissions',
    roleHasPermissions: 'role_has_permissions',
    modelHasRoles: 'model_has_roles',
    modelHasPermissions: 'model_has_permissions',
  },
  columnNames: {
    rolePivotKey: 'role_id',
    permissionPivotKey: 'permission_id',
    modelMorphKey: 'model_id',
    modelMorphType: 'model_type',
    teamForeignKey: 'team_id',
  },
})

Change table/column names before running the migrations, and keep your migrations in sync with the config.

Roles, permissions, models and teams can use increments, bigIncrements or uuid primary keys, even mixed in the same app. Polymorphic columns (model_id, team_id) are generated as string so they hold any of them.

For UUIDs, let the model assign its own key:

import { randomUUID } from 'node:crypto'
import { compose } from '@adonisjs/core/helpers'
import { BaseModel, beforeCreate, column } from '@adonisjs/lucid/orm'
import { Roleable } from '@eienjs/adonisjs-permission'

export default class Role extends compose(BaseModel, Roleable) {
  static selfAssignPrimaryKey = true

  @column({ isPrimary: true })
  declare id: string

  @beforeCreate()
  static assignUuid(role: Role) {
    role.id ||= randomUUID()
  }
}

Then change table.increments('id') to table.uuid('id').primary() and the pivot foreign keys to table.uuid(...) in your migrations. For bigIncrements, consume the value as BigInt with @column({ isPrimary: true, consume: BigInt }).

Installation

Install and configure the package with a single Ace command.

Roles & Permissions

Create roles and permissions and assign them to models.

Configuration

Options

Custom table and column names

Primary key types