effect-cdp

Type-safe Chrome DevTools Protocol client for Effect, built on @effect/platform with full streaming and error handling.

Generated from the devtools-protocol JSON schemas — 58 domains, typed commands, events, and results.

Install

# Bun
bun add effect-cdp effect@beta @effect/platform-bun@beta

# Node.js
npm install effect-cdp effect@beta @effect/platform-node@beta

Quickstart

Bun

import { Effect, Layer, Stream } from "effect";
import { Cdp, CdpConfig, SessionId } from "effect-cdp";
import * as Target from "effect-cdp/generated/Target.js";

const config = CdpConfig.make({
  webSocketDebuggerUrl: "ws://localhost:9222/devtools/browser/<id>",
  eventBufferSize: 256,
});

const program = Effect.gen(function* () {
  const cdp = yield* Cdp;

  // Send a command
  const { targetId } = yield* cdp.root.send(Target.createTarget, {
    url: "about:blank",
  });

  // Get session and listen to events
  const session = cdp.session(SessionId.makeUnsafe(targetId));
  const events = yield* Stream.runCollect(session.events);

  return events;
}).pipe(Effect.provide(Cdp.layerBun(config)));

Effect.runPromise(program);

Node.js

import { Cdp } from "effect-cdp";

const program = Effect.gen(function* () {
  const cdp = yield* Cdp;
  // ...
}).pipe(Effect.provide(Cdp.layerNode(config)));

Auth Headers (e.g., Cloak, Browserless)

Some CDP proxies require Authorization headers on the WebSocket handshake. Install ws and use layerWithAuthHeaders:

bun add ws

import { layerWithAuthHeaders } from "effect-cdp";

const cdpLayer = layerWithAuthHeaders(config, {
  Authorization: "Bearer <token>",
});

const program = Effect.gen(function* () {
  const cdp = yield* Cdp;
  // ...
}).pipe(Effect.provide(cdpLayer));

Cloudflare Workers

The ws library does not run in Cloudflare Workers. Use layerCloudflare instead — it performs the WebSocket upgrade via fetch with custom headers and accepts the socket from the 101 response:

import { layerCloudflare } from "effect-cdp";

const cdpLayer = layerCloudflare(config, {
  Authorization: "Bearer <token>",
});

const program = Effect.gen(function* () {
  const cdp = yield* Cdp;
  // ...
}).pipe(Effect.provide(cdpLayer));

This only works in runtimes that support Cloudflare's non-standard fetch WebSocket upgrade (e.g., Cloudflare Workers, Wrangler local dev).

Reconnect

Connection drops happen. Add automatic reconnection with exponential backoff:

const config = CdpConfig.make({
  webSocketDebuggerUrl: "ws://localhost:9222/devtools/browser/<id>",
  eventBufferSize: 256,
  reconnect: {
    maxRetries: 3,
    baseDelay: Duration.millis(1000),
  },
});

const program = Effect.gen(function* () {
  const cdp = yield* Cdp;
  // ...
}).pipe(Effect.provide(Cdp.layerBun(config)));

When reconnect is set, the initial socket connection retries with exponential backoff before failing.

Feature Matrix

| Feature | Status | Notes | | ----------------------------------------- | ------ | ---------------------------------------- | | Command/response | Ready | Typed via Effect Schema | | Event streaming | Ready | Stream.Stream<RawCdpEvent> per session | | Session multiplexing | Ready | Multiple targets, one connection | | Error handling | Ready | 4 typed errors (see below) | | Bun runtime | Ready | Cdp.layerBun(config) | | Node.js runtime | Ready | Cdp.layerNode(config) | | Helpers (Page.goto, Runtime.evaluate) | Ready | Type-safe wrappers in helpers/ | | Codegen (58 domains) | Ready | Auto-generated from devtools-protocol |

v1 Scope OUT

These features are intentionally deferred to post-v1:

• Bidi/WebDriver BiDi protocol support
• Built-in session pooling
• Retry/circuit-breaker policies
• Request deduplication
• Browser download/management

Backpressure Note

Event buffering uses a dropping queue. When eventBufferSize is exceeded, events are dropped and a metric counter cdp_events_dropped_total is incremented. If you need lossless event delivery, increase eventBufferSize or consume events faster than they are produced.

Errors

All errors are typed Schema.TaggedError with a _tag discriminator:

| Error | _tag | When it occurs | | ------------------ | ------------------ | --------------------------------------------------------------- | | CdpDisconnected | CdpDisconnected | Socket closed, scope finalized, target detached, or peer killed | | CdpTimeout | CdpTimeout | Command exceeds timeout duration | | CdpDecodeError | CdpDecodeError | Response JSON cannot be decoded to expected schema | | CdpProtocolError | CdpProtocolError | CDP returns an error response (check code and message) |

Handle errors with Effect.catchTag:

yield *
  cdp.root
    .send(Page.navigate, { url })
    .pipe(
      Effect.catchTag("CdpTimeout", (err) =>
        Effect.log(`Navigation timed out after ${err.durationMs}ms`),
      ),
    );

License

MIT