Packages

AdonisJS Plus packages are the foundation behind Kit components. In this guide, you will learn:

• What packages are available and what they do
• How packages relate to Kit components
• When to use packages directly instead of Kit

Overview

AdonisJS Plus ships two types of building blocks, ie Kit components and packages. Kit components are pre-built fullstack features you add to your application with a single command. They handle migrations, model setup, and configuration for you. Packages are the libraries that power those components.

Most users should start with Kit components. Use packages directly when:

• You need only a specific feature that Kit does not bundle as a standalone component.
• Your application architecture diverges from the conventions Kit assumes.
• You want to understand the internals and build custom workflows on top of the lower-level APIs.

The package documentation serves as API reference and learning material. You will find the required database schemas, configuration options, and method references for every feature. If you are looking for step-by-step setup guides, start with the Kit documentation instead.

Available packages

Persona

@adonisplus/persona provides Lucid model mixins for common user account operations.

• Email management handles email verification flows with a two-column pattern, cryptographic tokens, and atomic email switching.
• Password management handles password reset flows with secure tokens and atomic password updates.
• TOTP management handles two-factor authentication with authenticator app enrollment, QR codes, and recovery codes.
• Social identity handles OAuth provider identity linking with secure identity resolution, snapshot tracking, and account management. Works directly with @adonisjs/ally user objects.

Each module is independent. You can use email management without password management, or add social identity later without touching your existing setup. You apply them to your User model using the compose helper from AdonisJS.

import { compose } from '@adonisjs/core/helpers'
import { BaseModel } from '@adonisjs/lucid/orm'
import { withManagedEmail } from '@adonisplus/persona/email'
import { withTotpManagement } from '@adonisplus/persona/totp'
import { withSocialIdentity } from '@adonisplus/persona/social'
import { withManagedPassword } from '@adonisplus/persona/password'

export default class User extends compose(
  BaseModel,
  withManagedEmail(),
  withManagedPassword(),
  withTotpManagement(encryption, hash),
  withSocialIdentity()
) {}

Permissions

@adonisplus/permissions provides a declarative role-based permission system with Bouncer integration.

• Define permissions using a resource/action pattern with support for prefixes, aliases, and inactive states.
• Assign permissions directly to models or through roles using Lucid mixins.
• Check access through the Access class or generate Bouncer abilities automatically from your permission definitions.

import { definePermissions, prefix } from '@adonisplus/permissions'

export const permissions = definePermissions(
  prefix('admin', {
    product: { create: true, update: true, delete: true },
  }),
  {
    billing: { refund: 'Issue refunds' },
  }
)