> ## 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.

# Puppeteer

> Connect Driver sessions to Puppeteer

[Puppeteer](https://pptr.dev) is Google's Node.js library for controlling Chrome/Chromium via the DevTools Protocol.

## Installation

```bash theme={null}
npm install puppeteer-core @browsercash/sdk
```

<Note>
  Use `puppeteer-core` instead of `puppeteer` — Driver provides the browser, so you don't need Puppeteer to download one.
</Note>

## Quick Start

```typescript TypeScript theme={null}
import puppeteer from 'puppeteer-core';
import BrowsercashSDK from '@browsercash/sdk';

async function run() {
  const client = new BrowsercashSDK({
    apiKey: process.env.DRIVER_API_KEY!,
    baseURL: "https://api.driver.dev",
  });

  // Create a Driver session
  const session = await client.browser.session.create({ type: 'hosted' });

  // Connect Puppeteer via CDP
  const browser = await puppeteer.connect({
    browserWSEndpoint: session.cdpUrl,
  });

  // Automate
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());

  // Cleanup
  await browser.disconnect();
  await client.browser.session.stop({ sessionId: session.sessionId });
}

run().catch(console.error);
```

## With Session Options

```typescript TypeScript theme={null}
const session = await client.browser.session.create({
  country: 'GB',
  type: 'hosted',
  windowSize: '1366x768',
});

const browser = await puppeteer.connect({
  browserWSEndpoint: session.cdpUrl,
});
```

## Taking Screenshots

```typescript TypeScript theme={null}
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png', fullPage: true });
```

## Generating PDFs

```typescript TypeScript theme={null}
const page = await browser.newPage();
await page.goto('https://example.com');
await page.pdf({ path: 'page.pdf', format: 'A4' });
```

## With Persistent Profiles

```typescript TypeScript theme={null}
// Create session with profile
const session = await client.browser.session.create({
  type: 'hosted',
  profile: { name: 'logged-in-user', persist: true },
});

const browser = await puppeteer.connect({
  browserWSEndpoint: session.cdpUrl,
});

// Cookies and localStorage persist across sessions
```

## Error Handling

```typescript TypeScript theme={null}
try {
  const browser = await puppeteer.connect({
    browserWSEndpoint: session.cdpUrl,
  });
  // ... automation
} catch (error) {
  if (error.message.includes('Connection closed')) {
    console.log('Session disconnected');
  }
  throw error;
} finally {
  await client.browser.session.stop({ sessionId: session.sessionId });
}
```

## Tips

* Use `browser.disconnect()` instead of `browser.close()` to keep the remote session running
* Use `hosted` sessions for predictable managed Chrome infrastructure