Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.driver.dev/llms.txt

Use this file to discover all available pages before exploring further.

Scale your browser automation with pooled sessions that handle concurrency, health checks, and automatic recovery.

​
Installation

npm install @browsercash/pool playwright-core
The @browsercash/pool package requires playwright-core as a peer dependency.

​
Quick Start

TypeScript
import { chromium } from "playwright-core";
import { SessionPool } from "@browsercash/pool";

const pool = new SessionPool({
  apiKey: process.env.DRIVER_API_KEY!,
  chromium: chromium,
  size: 3, // Maintain 3 concurrent sessions
});

await pool.init();

// Acquire a session from the pool
const session = await pool.acquire();

// Use standard Playwright operations
const page = await session.browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await page.close();

// Return session to the pool
pool.release(session);

// Cleanup when done
await pool.shutdown();

​
Pool Options

Configure the pool behavior with these options:
OptionTypeDefaultDescription
apiKeystringRequiredYour Driver API key
chromiumChromiumModuleRequiredPlaywright chromium instance
sizenumber1Number of concurrent sessions to maintain
maxUsesnumber50Maximum requests per session before recycling
maxAgeMsnumber300000Maximum session lifetime in milliseconds (5 min)
enableHealthCheckbooleanfalseEnable background health monitoring
healthCheckIntervalMsnumber30000Health check frequency in milliseconds
enableWaitQueuebooleantrueQueue requests when all sessions are busy
debugbooleanfalseEnable verbose logging

​
Configuration Examples

​
High-Throughput Pool

TypeScript
const pool = new SessionPool({
  apiKey: process.env.DRIVER_API_KEY!,
  chromium: chromium,
  size: 10, // 10 concurrent browsers
  maxUses: 100, // Recycle after 100 uses
  maxAgeMs: 600000, // 10 minute max lifetime
  enableWaitQueue: true, // Queue when pool is full
});

​
Long-Running Pool with Health Checks

TypeScript
const pool = new SessionPool({
  apiKey: process.env.DRIVER_API_KEY!,
  chromium: chromium,
  size: 5,
  enableHealthCheck: true, // Monitor session health
  healthCheckIntervalMs: 15000, // Check every 15 seconds
  maxAgeMs: 1800000, // 30 minute max lifetime
});

​
Pool Methods

​
init()

Initialize the pool and create the initial sessions:
TypeScript
const pool = new SessionPool({
  /* options */
});
await pool.init();

​
acquire()

Get an available session from the pool. If all sessions are busy and enableWaitQueue is true, the request will wait:
TypeScript
const session = await pool.acquire();
// session.browser is a Playwright Browser instance

​
release(session)

Return a session to the pool for reuse:
TypeScript
pool.release(session);
Always release sessions back to the pool. Failing to release sessions will exhaust the pool and block subsequent requests.

​
shutdown()

Gracefully close all sessions and clean up resources:
TypeScript
await pool.shutdown();

​
Parallel Processing Example

Process multiple URLs concurrently using the pool:
TypeScript
import { chromium } from "playwright-core";
import { SessionPool } from "@browsercash/pool";

const pool = new SessionPool({
  apiKey: process.env.DRIVER_API_KEY!,
  chromium: chromium,
  size: 5,
});

await pool.init();

const urls = [
  "https://example.com",
  "https://example.org",
  "https://example.net",
  // ... more URLs
];

async function scrapeUrl(url: string) {
  const session = await pool.acquire();
  try {
    const page = await session.browser.newPage();
    await page.goto(url);
    const title = await page.title();
    await page.close();
    return { url, title };
  } finally {
    pool.release(session);
  }
}

// Process all URLs with controlled concurrency
const results = await Promise.all(urls.map(scrapeUrl));
console.log(results);

await pool.shutdown();

​
Next Steps