Implementation:Puppeteer Puppeteer EventEmitter

Property	Value
sources	packages/puppeteer-core/src/common/EventEmitter.ts
domains	Events, Core Infrastructure, Observer Pattern
last_updated	2026-02-12 00:00 GMT

Overview

Description

EventEmitter is the core event system class that many Puppeteer classes extend. It provides a type-safe, generic event emitter built on top of the mitt library (a tiny functional event emitter). The class supports binding, unbinding, and emitting events with full TypeScript generic support for event type maps.

The module exports several types:

• EventType -- A union of string | symbol representing valid event key types.
• Handler<T> -- A function type (event: T) => void for event handlers.
• CommonEventEmitter -- An interface defining the standard event emitter contract (on, off, emit, once, listenerCount, removeAllListeners).
• EventsWithWildcard -- A utility type that adds a wildcard '*' event that receives all events.

The EventEmitter class supports the [Symbol.dispose] protocol for resource cleanup, allowing it to be used with the using keyword to automatically clean up all listeners.

Usage

EventEmitter is the base class for Page, Browser, BrowserContext, CDPSession, and many other Puppeteer classes. Users interact with it primarily through the on, off, and once methods to listen for events.

Code Reference

Source Location

packages/puppeteer-core/src/common/EventEmitter.ts

Signature

export type EventType = string | symbol;
export type Handler<T = unknown> = (event: T) => void;

export interface CommonEventEmitter<Events extends Record<EventType, unknown>> {
  on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): this;
  off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): this;
  emit<Key extends keyof Events>(type: Key, event: Events[Key]): boolean;
  once<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): this;
  listenerCount(event: keyof Events): number;
  removeAllListeners(event?: keyof Events): this;
}

export type EventsWithWildcard<Events extends Record<EventType, unknown>> =
  Events & { '*': Events[keyof Events] };

export class EventEmitter<Events extends Record<EventType, unknown>>
  implements CommonEventEmitter<EventsWithWildcard<Events>> {
  constructor(emitter?: Emitter<EventsWithWildcard<Events>> | EventEmitter<Events>);
  on<Key extends keyof EventsWithWildcard<Events>>(type: Key, handler: Handler<EventsWithWildcard<Events>[Key]>): this;
  off<Key extends keyof EventsWithWildcard<Events>>(type: Key, handler?: Handler<EventsWithWildcard<Events>[Key]>): this;
  emit<Key extends keyof EventsWithWildcard<Events>>(type: Key, event: EventsWithWildcard<Events>[Key]): boolean;
  once<Key extends keyof EventsWithWildcard<Events>>(type: Key, handler: Handler<EventsWithWildcard<Events>[Key]>): this;
  listenerCount(type: keyof EventsWithWildcard<Events>): number;
  removeAllListeners(type?: keyof EventsWithWildcard<Events>): this;
  [Symbol.dispose](): void;
}

Import

import {EventEmitter, type EventType, type Handler, type CommonEventEmitter} from 'puppeteer-core/lib/esm/puppeteer/common/EventEmitter.js';

I/O Contract

Method	Parameters	Return Type	Description
on(type, handler)	event key, handler function	this	Binds an event listener; chainable
off(type, handler?)	event key, optional handler	this	Removes a specific listener or all listeners for the type; chainable
emit(type, event)	event key, event data	boolean	Emits an event; returns true if listeners exist
once(type, handler)	event key, handler function	this	Binds a one-time listener; chainable
listenerCount(type)	event key	number	Returns the number of listeners for the given event
removeAllListeners(type?)	optional event key	this	Removes all listeners (or all for a specific event); chainable

Usage Examples

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();

// Listen for page events using the EventEmitter API
page.on('console', (msg) => {
  console.log('Console:', msg.text());
});

// One-time listener
page.once('load', () => {
  console.log('Page loaded!');
});

// Check listener count
console.log('Console listeners:', page.listenerCount('console'));

// Remove all listeners for a specific event
page.removeAllListeners('console');

// Wildcard listener (receives all events)
page.on('*', (event) => {
  console.log('Received event:', event);
});

await page.goto('https://example.com');
await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime