You are viewing the legacy version of AdonisJS. Visit for newer docs. This version will receive security patches until the end of 2021.


AdonisJs got a beautiful Event Emitter to emit and listen to events with support for ES2015 generators, wildcards and a dedicated directory to store/manage listeners.

About Events

  1. Events are defined inside bootstrap/events.js file.

  2. Events listeners can be defined as Closures or you can bind an IoC container namespace.

    Event.on('user.registered', function * (user) {
    // OR
    Event.on('user.registered', 'User.registered')
  3. The app/Listeners directory is dedicated for storing Event listeners.

  4. When binding listeners to the events, you are not required to enter the entire namespace. For example A listener stored as app/Listeners/User.js will be referenced as User.<method>.

  5. Make use of make:listener command to create a new event listener.

    ./ace make:listener User
    # create: app/Listeners/User.js


The configuration for Events provider is stored inside config/events.js file. Under the hood AdonisJs makes use of EventEmitter 2 and implements all the available configuration options.

Basic Example

Let’s walk through a basic example of sending a welcome email to a newly registered user using the Events provider. We will start by setting up a route and will use the UsersController to fire the event after creating a new user.

'use strict'

const Route = use('Route')'users', '')
'use strict'

const Event = use('Event')
Event.when('user.registered', 'User.sendWelcomeEmail') (1)
'use strict'

const Event = use('Event')
const User = use('App/Model/User')

class UsersController {
  * store (request, response) {
    const user = yield User.create(userDetails)'user.registered', user.toJSON()) (2)
'use strict'

const Mail = use('Mail')
const User = exports = module.exports = {}

User.sendWelcomeEmail = function * (user) {
  yield Mail.send('emails.welcome', user, message => {, user.firstname)
    message.subject('Welcome to the Kitten\'s World')
1 First we need to register a listener for the event.
2 The method will fire the user.registered event and pass the newly created user.

Event Methods

Below is the list of available methods exposed by the Event Provider.

when(event, [name], listener)

Register a listener for a given event. You can also define an optional name for a listener, which can be used to remove it later.

Event.when('user.registered', 'Mail.sendWelcomeEmail')
Event.when('user.registered', function * () {
  // ...
Event.when('user.registered', 'registration', 'User.sendWelcomeEmail')
Table 1. Aliases
Alias Example


Event.listen('user.registered', function * () {})


Event.on('user.registered', function * () {})

once(event, handler)

Works same as when but is executed only for one time.

Event.once('app.boot', function * () {
  // ...


Attach a global event listener to listen for all the events.

Event.any(function (event) {


Set a limit for times an event listener will be executed and get removed after that.

Event.times(4).when('user.registered', function () {
  // I will be executed 4 times only

fire(event, data)

Fires an event.'user.registered', user)
Table 2. Aliases
Alias Example


Event.emit('user.registered', user)


Remove all listeners from a given event or for all events.

Event.removeListeners() // will remove all listeners
Event.removeListeners('user.registered') // will remove listeners for user.registered event only

removeListener(event, name)

Remove a named listener for a given event.

// register multiple
Event.when('user.registered', 'Logger.log')
Event.when('user.registered', 'registration', 'Mail.sendWelcomeEmail')

// remove a specific one
Event.removeListener('user.registered', 'registration')


Returns a boolean whether an event has listeners or not.



Returns an array of listeners for a specific event.


Emitter Instance

All of the event listeners has access to the emitter instance.

Event.when('user.registered', function () {