Skip to main content
The Events module re-exports all functionality from @adonisjs/events, providing a type-safe event emitter for building event-driven applications.

​
Import

import { Emitter } from '@adonisjs/core/events'
import type { EventsList } from '@adonisjs/core/events'

​
Overview

The Events module provides an event emitter implementation that allows different parts of your application to communicate through events. It supports both synchronous and asynchronous event listeners with full TypeScript support.

​
Classes

​
Emitter

The main event emitter class for dispatching and listening to events.

​
Constructor

​
app
Application
The AdonisJS application instance (typically injected automatically)

​
Methods

on
Registers an event listener.
​
event
string
required
The event name to listen for
​
handler
function
required
The callback function to execute when the event is emitted. Can be synchronous or asynchronous.
​
return
void
No return value
import emitter from '@adonisjs/core/services/emitter'

emitter.on('user:registered', async (user) => {
  // Send welcome email
  await sendWelcomeEmail(user)
})
once
Registers a one-time event listener that is automatically removed after being called once.
​
event
string
required
The event name to listen for
​
handler
function
required
The callback function to execute when the event is emitted
​
return
void
No return value
emitter.once('app:ready', () => {
  console.log('Application is ready!')
})
emit
Emits an event with optional data.
​
event
string
required
The event name to emit
​
data
any
Optional data to pass to event listeners
​
return
Promise<void>
A promise that resolves when all listeners have finished executing
await emitter.emit('user:registered', {
  id: user.id,
  email: user.email,
  name: user.name
})
off
Removes an event listener.
​
event
string
required
The event name
​
handler
function
The specific handler to remove. If omitted, removes all handlers for the event.
​
return
void
No return value
const handler = (user) => console.log(user)
emitter.on('user:registered', handler)

// Later, remove the listener
emitter.off('user:registered', handler)
clearListeners
Removes all listeners for a specific event or all events.
​
event
string
Optional event name. If omitted, clears all listeners for all events.
​
return
void
No return value
// Clear all listeners for a specific event
emitter.clearListeners('user:registered')

// Clear all listeners for all events
emitter.clearListeners()
listenerCount
Returns the number of listeners for an event.
​
event
string
required
The event name
​
return
number
The number of registered listeners for the event
const count = emitter.listenerCount('user:registered')
console.log(`${count} listeners registered for user:registered event`)

​
Types

​
EventsList

Type definition for declaring application events with their data types. 
declare module '@adonisjs/core/types' {
  interface EventsList {
    'user:registered': { id: number; email: string; name: string }
    'order:placed': { orderId: string; total: number }
    'email:sent': { to: string; subject: string }
  }
}

​
Example Usage

​
Defining Events

// In types/events.ts
declare module '@adonisjs/core/types' {
  interface EventsList {
    'user:registered': {
      id: number
      email: string
      name: string
    }
    'user:updated': {
      id: number
      changes: Record<string, any>
    }
    'user:deleted': {
      id: number
    }
  }
}

​
Listening to Events

import emitter from '@adonisjs/core/services/emitter'

// Single listener
emitter.on('user:registered', async (user) => {
  await sendWelcomeEmail(user.email)
})

// Multiple listeners for the same event
emitter.on('user:registered', async (user) => {
  await createUserProfile(user.id)
})

emitter.on('user:registered', async (user) => {
  await logUserRegistration(user)
})

// One-time listener
emitter.once('app:ready', () => {
  console.log('Application started successfully')
})

​
Emitting Events

import emitter from '@adonisjs/core/services/emitter'

class UserController {
  async register({ request, response }: HttpContext) {
    const user = await User.create(request.all())
    
    // Emit event (all listeners will be called)
    await emitter.emit('user:registered', {
      id: user.id,
      email: user.email,
      name: user.name
    })
    
    return response.json(user)
  }
}

​
Creating Event Listeners

// In app/listeners/user_registered.ts
import emitter from '@adonisjs/core/services/emitter'
import mail from '@adonisjs/mail/services/main'

class UserRegisteredListener {
  async handle(data: { id: number; email: string; name: string }) {
    await mail.send((message) => {
      message
        .to(data.email)
        .subject('Welcome!')
        .htmlView('emails/welcome', { name: data.name })
    })
  }
}

// Register the listener
const listener = new UserRegisteredListener()
emitter.on('user:registered', listener.handle.bind(listener))

​
Notes

  • All event listeners are executed sequentially in the order they were registered
  • Async listeners are awaited, so errors in listeners can be caught
  • TypeScript provides autocomplete for event names and data types when properly declared
  • The emitter instance is typically available via the @adonisjs/core/services/emitter service
  • Events are a great way to decouple different parts of your application