@swarmmachina/swm-cdp v0.1.1

swm-cdp

Chrome DevTools Protocol

A typed ESM Chrome DevTools Protocol client with zero runtime dependencies. Commands, events, and flattened sessions with explicit ownership of the Chrome process.

Use it for browser smoke tests, diagnostics, and local Chrome control at the protocol level. The package is experimental; high-level locators and automatic element waiting remain outside its API.

Node.jsswm-cdpCDP pipe / WebSocketChrome
22 / 24
Node.js
0
runtime deps
ESM
module format
MPL-2.0
license

Installation and quick start

Shellinstall
npm install @swarmmachina/swm-cdp
JavaScriptquick-start.js
import { spawnChrome } from '@swarmmachina/swm-cdp'

const browser = spawnChrome({ headless: true, transport: 'pipe' })

try {
  const cdp = await browser.attach()
  const target = await cdp.send('Target.createTarget', { url: 'about:blank' })
  const { sessionId } = await cdp.send('Target.attachToTarget', {
    flatten: true,
    targetId: target.targetId
  })

  await cdp.send('Runtime.enable', undefined, sessionId)
  const result = await cdp.send(
    'Runtime.evaluate',
    { expression: 'document.title', returnByValue: true },
    sessionId
  )
  console.log(result.result.value)
} finally {
  await browser.close()
}
  • Install Chrome or Chromium separately; set chromeExecutable or CHROME_PATH for an explicit executable path.
  • spawnChrome() synchronously creates the process owner; attach() is the separate asynchronous CDP readiness stage.
  • Pass sessionId to page commands. Use undefined before sessionId when a command has no parameters.
  • browser.close() stops the owned Chrome process and removes its temporary profile. Closing the client from attach() also closes its owner.

Package capabilities

Typed protocol
send(), on(), and once() use generated CDP command, result, and event types.
Chrome ownership
Browser separates creation, attachment, shutdown, and profile cleanup; pipe is the default transport.
Bounded queues
Limits for pending requests, task queues, messages, and outbound buffers; eventBackpressure closes on overflow by default.
Discovery and finder
HTTP discovery uses built-in fetch; findChrome() locates an executable without launching a browser.

Runtime and platforms

EnvironmentStatusNote
Node.js ^22.13.0 / 24.xSupportedNative ESM and built-in WebSocket; Node.js 26 is outside the engine range.
Local Chrome / ChromiumSeparate installationThe browser is not bundled with the npm package.
127.0.0.1 / [::1]WebSocket endpointconnect() accepts browser-level endpoints only on literal loopback IPs; localhost and remote addresses are rejected.

API map

CdpClient

Typed commands, events, and connection closure.

connect()send()on()once()onClose()onError()close()

Browser

Explicit owner of the Chrome process and temporary profile.

spawnChrome()attach()close()kill()waitForExit()state

Discovery / finder

Separate subpath exports for executable lookup and HTTP discovery.

list()version()createTarget()closeTarget()findChrome()ChromeFinder

Complete signatures, types, and examples are available in the source repository README and TypeScript declarations.

Sessions, limits, and Chrome shutdown

Distinguish the protocol client lifecycle from the lifecycle of an owned browser process.

Close the owner in finally

Use browser.close() for spawnChrome(). With connect(), cdp.close() closes only the client and leaves independently started Chrome running.

Filter events by sessionId

on() passes sessionId as its second argument and returns an unsubscribe function. Call it when the subscription is no longer needed.

Bound operations

send() accepts an AbortSignal and timeout; protocolTimeout defaults to 180 seconds, and maxPendingRequests and maxQueueDepth default to 10,000.

Keep the local boundary

Remote endpoints and DNS names are deliberately rejected. Keep the browser debugging endpoint off the public network.

Connect to an existing Chrome process

When Chrome already exposes a debugging endpoint on loopback, connect() creates only a client connection. The external process owner remains responsible for stopping Chrome.

JavaScriptconnect.js
import connect from '@swarmmachina/swm-cdp'

const cdp = await connect({ host: '127.0.0.1', port: 9222 })

try {
  console.log(await cdp.send('Browser.getVersion'))
} finally {
  await cdp.close()
}
Need HTTP or WebSocket load instead of browser control?Open benchkit