Implementation:Puppeteer Puppeteer WebWorker

Sources	packages/puppeteer-core/src/api/WebWorker.ts
Domains	Web Workers, JavaScript Evaluation, Background Processing
Last Updated	2026-02-12

Overview

WebWorker is the abstract base class that represents a Web Worker running in the browser, providing methods to evaluate JavaScript within the worker's execution context.

Description

The WebWorker class extends EventEmitter and models a browser Web Worker as defined by the Web Workers API. It stores the worker's URL as a private field and exposes it through the url() method. The class also holds a TimeoutSettings instance for configuring evaluation timeouts.

The class provides two evaluation methods. The evaluate() method runs a function (or string expression) in the worker's context and returns the deserialized result -- if the function returns a promise, it waits for resolution. For complex return values that cannot be serialized cleanly, the evaluateHandle() method returns a JSHandle to the result instead, preserving a live reference to the object in the worker's runtime.

Both evaluation methods delegate to the abstract mainRealm() method, which concrete subclasses must implement to provide the worker's execution realm. The abstract client property exposes the underlying CDP session.

The close() method throws an UnsupportedOperation error by default, as closing workers is not universally supported.

Worker lifecycle events (workercreated and workerdestroyed) are emitted on the parent Page object, not on the worker itself.

Usage

WebWorker instances are obtained from the parent Page via page.workers() or through the workercreated event. They can also be accessed through Target.worker() for service worker and shared worker targets.

Code Reference

Source Location

packages/puppeteer-core/src/api/WebWorker.ts

Signature

export abstract class WebWorker extends EventEmitter<Record<EventType, unknown>> {
  readonly timeoutSettings: TimeoutSettings;
  constructor(url: string);
  abstract mainRealm(): Realm;
  url(): string;
  abstract get client(): CDPSession;
  async evaluate<Params extends unknown[], Func extends EvaluateFunc<Params>>(
    func: Func | string, ...args: Params
  ): Promise<Awaited<ReturnType<Func>>>;
  async evaluateHandle<Params extends unknown[], Func extends EvaluateFunc<Params>>(
    func: Func | string, ...args: Params
  ): Promise<HandleFor<Awaited<ReturnType<Func>>>>;
  async close(): Promise<void>;
}

Import

import type {WebWorker} from 'puppeteer-core/src/api/WebWorker.js';

I/O Contract

Inputs

Parameter	Type	Description
url (constructor)	string	The URL of the web worker script
func (evaluate)	string	Function or string expression to evaluate in the worker context
args (evaluate)	Params	Arguments to pass into the evaluation function
func (evaluateHandle)	string	Function or string expression to evaluate, returning a handle
args (evaluateHandle)	Params	Arguments to pass into the evaluation function

Outputs

Method	Return Type	Description
url()	string	The URL of the web worker
client	CDPSession	The CDP session the worker belongs to
evaluate()	Promise<Awaited<ReturnType<Func>>>	Deserialized result of the evaluated function
evaluateHandle()	Promise<HandleFor<Awaited<ReturnType<Func>>>>	A JSHandle to the result of the evaluated function
mainRealm()	Realm	The worker's main execution realm

Usage Examples

// Monitor worker lifecycle
page.on('workercreated', worker =>
  console.log('Worker created: ' + worker.url()),
);
page.on('workerdestroyed', worker =>
  console.log('Worker destroyed: ' + worker.url()),
);

console.log('Current workers:');
for (const worker of page.workers()) {
  console.log('  ' + worker.url());
}

// Evaluate an expression in a worker
const workers = page.workers();
const worker = workers[0];
const result = await worker.evaluate(() => {
  return self.name;
});
console.log(result);

// Use evaluateHandle for complex objects in a worker
const worker = page.workers()[0];
const handle = await worker.evaluateHandle(() => {
  return { nested: { data: [1, 2, 3] } };
});
const json = await handle.jsonValue();
console.log(json); // { nested: { data: [1, 2, 3] } }
await handle.dispose();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime