Stacks Event Listeners
Application-level event listeners in app/Listeners/.
Key Paths
- Listeners:
app/Listeners/ - Event mapping:
app/Events.ts - Listener setup:
app/Listener.ts
Event → Listener Mapping (app/Events.ts)
export default {
'user:registered': ['SendWelcomeEmail'], // triggers app/Actions/SendWelcomeEmail.ts
'user:created': ['NotifyUser'], // triggers app/Actions/NotifyUser.ts
'order:created': ['ProcessPayment', 'SendOrderConfirmation'], // multiple listeners
} satisfies Events
Keys are event names. Values are arrays of Action names from app/Actions/.
How Listeners Work
- Events are dispatched:
dispatch('user:registered', { id: 1 }) - The wildcard handler in
app/Listener.tscatches ALL events - Checks if the event has registered listeners in
app/Events.ts - For each listener, dynamically imports
app/Actions/{listener}.ts - Calls
action.handle(eventData) - Action modules are cached after first import
Creating a Listener Action
// app/Actions/SendWelcomeEmail.ts
export default {
name: 'SendWelcomeEmail',
async handle(event: { id: number; email: string; name: string }) {
// event contains the data passed to dispatch()
await sendWelcomeEmail({ to: event.email, name: event.name })
return { success: true }
}
}
CLI Event Listeners (app/Listeners/Console.ts)
For CLI-specific events (not HTTP):
export default function(cli: CLI) {
// Specific command
cli.on('inspire:three', () => {
console.log(getThreeQuotes())
})
// Default handler (unknown commands)
cli.on('inspire:!', () => {
console.log('Unknown inspire command')
})
// Wildcard (matches inspire:anything)
cli.on('inspire:*', () => {
console.log('Some inspire variant')
})
}
Multiple Listeners Per Event
// app/Events.ts
{
'order:created': [
'ProcessPayment', // runs first
'SendOrderConfirmation', // runs second
'UpdateInventory', // runs third
'NotifyWarehouse' // runs fourth
]
}
Listeners execute sequentially (not in parallel) — each awaits completion.
Gotchas
- Listeners are Action names, not file paths —
'SendWelcomeEmail'resolves toapp/Actions/SendWelcomeEmail.ts - The action must have a
handle(event)method - Listeners run sequentially per event — order in the array matters
- Action modules are cached after first load — no hot-reload for listeners
- CLI listeners are separate from HTTP event listeners
- For the event API (dispatch, listen, emitter), see the
stacks-eventsskill
