🌊 Browser Pool

Robust browser session management for Playwright & Browser.cash.

Powered by Browser.cash remote browsers.

Features • Installation • Usage • Configuration • Contributing

💡 Pro Tip: See this library in action in Teracrawl and Browser SERP.

---

🚀 What is Browser Pool?

Browser Pool is a specialized library designed to manage pools of remote browser sessions. It handles the lifecycle of Playwright browsers connected to Browser.cash, ensuring your application always has a healthy browser ready to perform tasks.

It abstracts away the complexity of connection management, error recovery, and session recycling, making it ideal for building high-concurrency scrapers and automation tools.

✨ Features

• Automatic Pooling: Maintains a fixed number of active browser sessions.
• Self-Healing: Automatically detects and replaces dead or disconnected browsers.
• Health Checks: Periodically verifies browser responsiveness.
• Concurrency Control: Queues requests when all sessions are busy.
• Type-Safe: Written in TypeScript with full type definitions.

🛠️ Installation

npm install @browsercash/pool

Note: You must also have playwright-core installed as a peer dependency.

💻 Usage

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

// 1. Create the pool
const pool = new SessionPool({
  apiKey: process.env.BROWSER_API_KEY,
  chromium: chromium, // Inject your preferred chromium instance
  size: 3, // Maintain 3 concurrent sessions
});

// 2. Initialize
await pool.init();

// 3. Acquire a session (waits if none available)
const session = await pool.acquire();

try {
  // Use the standard Playwright browser instance
  const page = await session.browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  // 4. Always release the session back to the pool
  // Pass 'true' as second arg if the session encountered a fatal error
  pool.release(session);
}

// 5. Cleanup on shutdown
await pool.shutdown();

⚙️ Configuration

Option	Type	Default	Description
apiKey	string	Required	Your Browser.cash API key.
chromium	ChromiumModule	Required	The Playwright Chromium module.
size	number	1	Number of concurrent sessions to maintain.
maxUses	number	50	Max times a browser is reused before recycling.
maxAgeMs	number	300000	Max age (ms) of a session (default: 5 mins).
enableHealthCheck	boolean	false	Enable background health pings.
healthCheckIntervalMs	number	30000	Interval for health checks (ms).
enableWaitQueue	boolean	true	Queue acquire requests if pool is full.
debug	boolean	false	Enable verbose logging.

🤝 Contributing

Contributions are welcome! We appreciate your help in making Browser Pool better.

How to Contribute

1. Fork the Project: click the 'Fork' button at the top right of this page.
2. Create your Feature Branch: git checkout -b feature/AmazingFeature
3. Commit your Changes: git commit -m 'Add some AmazingFeature'
4. Push to the Branch: git push origin feature/AmazingFeature
5. Open a Pull Request: Submit your changes for review.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.