Implementation:Puppeteer Puppeteer NodeWebSocketTransport

Property	Value
sources	packages/puppeteer-core/src/node/NodeWebSocketTransport.ts
domains	Node, Transport, WebSocket
last_updated	2026-02-12 00:00 GMT

Overview

Description

The NodeWebSocketTransport class implements the ConnectionTransport interface using the ws (WebSocket) npm package. It provides the WebSocket-based communication layer between Puppeteer and the browser's DevTools protocol endpoint in Node.js environments.

The class provides:

• A static create factory method that establishes a WebSocket connection to a given URL with configurable headers. It returns a promise that resolves with a NodeWebSocketTransport instance once the connection is open, or rejects on error. The WebSocket is configured with redirect following enabled, per-message deflate disabled (for performance), synchronous events disabled, and a 256 MB max payload size. The User-Agent header is set to include the Puppeteer version.
• A send method that transmits a string message over the WebSocket.
• A close method that closes the WebSocket connection.
• onmessage and onclose callback properties that are invoked when messages are received or the connection closes.

Errors on the WebSocket are silently ignored to prevent unhandled error exceptions.

Usage

NodeWebSocketTransport is used internally by BrowserLauncher to establish CDP and WebDriver BiDi connections to the browser process over WebSocket.

Code Reference

Source Location

packages/puppeteer-core/src/node/NodeWebSocketTransport.ts

Signature

export class NodeWebSocketTransport implements ConnectionTransport {
  static create(
    url: string,
    headers?: Record<string, string>,
  ): Promise<NodeWebSocketTransport>;

  onmessage?: (message: NodeWebSocket.Data) => void;
  onclose?: () => void;

  constructor(ws: NodeWebSocket);
  send(message: string): void;
  close(): void;
}

Import

import {NodeWebSocketTransport} from '../node/NodeWebSocketTransport.js';

I/O Contract

Method	Parameter	Type	Description
create	url	string	The WebSocket URL to connect to (e.g., browser DevTools endpoint)
create	headers	Record<string, string>	Optional additional headers for the WebSocket handshake
send	message	string	The string message to send over the WebSocket

Method	Return Type	Description
create	Promise<NodeWebSocketTransport>	Resolves with a connected transport instance
send	void	Sends the message (fire and forget)
close	void	Closes the underlying WebSocket connection

Callback	Type	Description
onmessage	(message: NodeWebSocket.Data) => void	Called when a message is received from the browser
onclose	() => void	Called when the WebSocket connection closes

Usage Examples

// Create a WebSocket transport to the browser
const transport = await NodeWebSocketTransport.create(
  'ws://127.0.0.1:9222/devtools/browser/abc-123'
);

// Set up message handling
transport.onmessage = (data) => {
  const response = JSON.parse(data.toString());
  console.log('Received:', response);
};

transport.onclose = () => {
  console.log('Connection closed');
};

// Send a CDP command
transport.send(JSON.stringify({
  id: 1,
  method: 'Target.getTargets',
}));

// Close when done
transport.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime