CdpClient
Typed commands, events, and connection closure.
connect()send()on()once()onClose()onError()close()@swarmmachina/swm-cdp v0.1.1
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.
npm install @swarmmachina/swm-cdpimport { 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()
}| Environment | Status | Note |
|---|---|---|
| Node.js ^22.13.0 / 24.x | Supported | Native ESM and built-in WebSocket; Node.js 26 is outside the engine range. |
| Local Chrome / Chromium | Separate installation | The browser is not bundled with the npm package. |
| 127.0.0.1 / [::1] | WebSocket endpoint | connect() accepts browser-level endpoints only on literal loopback IPs; localhost and remote addresses are rejected. |
Typed commands, events, and connection closure.
connect()send()on()once()onClose()onError()close()Explicit owner of the Chrome process and temporary profile.
spawnChrome()attach()close()kill()waitForExit()stateSeparate subpath exports for executable lookup and HTTP discovery.
list()version()createTarget()closeTarget()findChrome()ChromeFinderComplete signatures, types, and examples are available in the source repository README and TypeScript declarations.
Distinguish the protocol client lifecycle from the lifecycle of an owned browser process.
Use browser.close() for spawnChrome(). With connect(), cdp.close() closes only the client and leaves independently started Chrome running.
on() passes sessionId as its second argument and returns an unsubscribe function. Call it when the subscription is no longer needed.
send() accepts an AbortSignal and timeout; protocolTimeout defaults to 180 seconds, and maxPendingRequests and maxQueueDepth default to 10,000.
Remote endpoints and DNS names are deliberately rejected. Keep the browser debugging endpoint off the public network.
When Chrome already exposes a debugging endpoint on loopback, connect() creates only a client connection. The external process owner remains responsible for stopping Chrome.
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()
}