> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> All the features and utilities for fast Node.js development with Browserbase.

If you're working with Node.js, the official `@browserbasehq/sdk` package is the easiest way
to connect to and control headless browsers running on Browserbase.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install -S @browserbasehq/sdk
  ```

  ```bash pnpm theme={null}
  pnpm install @browserbasehq/sdk
  ```

  ```bash yarn theme={null}
  yarn add @browserbasehq/sdk
  ```
</CodeGroup>

## Basic usage

Here's an example using the Browserbase Node.js SDK to create and connect to a session with Playwright:

```ts theme={null}
import { chromium } from "playwright-core";
import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY!,
});

// Create a new session
const session = await bb.sessions.create();

// Connect to the session
const browser = await chromium.connectOverCDP(session.connectUrl);

// Getting the default context to ensure the sessions are recorded
const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0];

await page.goto("https://news.ycombinator.com/");
await page.close();
await browser.close();

console.log(`Session complete! View recording at https://browserbase.com/sessions/${session.id}`);
```

## Session configuration

Pass configuration options when creating a session to customize browser behavior.

### All configuration options

```ts theme={null}
const session = await bb.sessions.create({
  // Project ID (optional - inferred from API key if not provided)
  projectId: "your-project-id",

  // Proxy configuration
  proxies: true, // Use default proxy

  // Region where the session runs
  region: "us-west-2",

  // Keep session alive after disconnection
  keepAlive: true,

  // Session timeout in seconds (60-21600)
  timeout: 3600,

  // Extension ID (uploaded via Upload Extension API)
  extensionId: "ext_abc123",

  // Browser settings
  browserSettings: {
    // Toggle features
    blockAds: true,
    solveCaptchas: true,
    recordSession: true,
    logSession: true,
    verified: true,

    // Operating system (only available with verified)
    // Controls user agent and environment signals
    os: "windows",

    // Context for session persistence
    context: {
      id: "my-context-id",
      persist: true,
    },

    // Viewport configuration (ignored when verified is enabled)
    viewport: {
      width: 1920,
      height: 1080,
    },

    // Custom CAPTCHA selectors
    captchaImageSelector: "#captcha-image",
    captchaInputSelector: "#captcha-input",
  },

  // Custom metadata for the session
  userMetadata: {
    userId: "user_123",
    taskName: "data-extraction-job",
  },
});
```

### Proxy configuration

Configure proxies as a boolean or as an array for more control:

```ts theme={null}
// Using Browserbase managed proxy with geolocation
const session = await bb.sessions.create({
  proxies: [
    {
      type: "browserbase",
      geolocation: {
        country: "US",
        state: "CA",
        city: "San Francisco",
      },
    },
  ],
});

// Using external proxy
const session = await bb.sessions.create({
  proxies: [
    {
      type: "external",
      server: "http://proxy.example.com:8080",
      username: "user",
      password: "pass",
      domainPattern: "*.example.com",
    },
  ],
});

// Multiple proxies with domain patterns
const session = await bb.sessions.create({
  proxies: [
    {
      type: "browserbase",
      geolocation: { country: "US" },
      domainPattern: "*.google.com",
    },
    {
      type: "external",
      server: "http://proxy.example.com:8080",
      domainPattern: "*.example.com",
    },
  ],
});
```

### Common configuration examples

```ts theme={null}
// Verified with proxy
const session = await bb.sessions.create({
  proxies: true,
  browserSettings: {
    verified: true,
    os: "windows",
  },
});

// Long-running session with keep-alive
const session = await bb.sessions.create({
  timeout: 21600, // 6 hours
  keepAlive: true,
});

// Session with context persistence
const session = await bb.sessions.create({
  browserSettings: {
    context: {
      id: "user-session-context",
      persist: true,
    },
  },
});

// Custom viewport and ad blocking
const session = await bb.sessions.create({
  browserSettings: {
    viewport: { width: 1440, height: 900 },
    blockAds: true,
  },
});

// Mobile viewport
const session = await bb.sessions.create({
  browserSettings: {
    viewport: { width: 390, height: 844 },
  },
});

// Session in specific region with metadata
const session = await bb.sessions.create({
  region: "eu-central-1",
  userMetadata: {
    jobId: "job_456",
    environment: "production",
  },
});
```

<CardGroup cols={2}>
  <Card title="Examples" icon="github" iconType="sharp-solid" href="https://github.com/browserbase/sdk-node/tree/main/examples">
    Quickstart examples using CAPTCHA solving, proxies, extensions, and more
  </Card>

  <Card title="npm package" icon="npm" iconType="sharp-solid" href="https://www.npmjs.com/package/@browserbasehq/sdk">
    View the package on NPM
  </Card>

  <Card title="SDK reference" icon="book" iconType="sharp-solid" href="https://github.com/browserbase/sdk-node/blob/main/api.md">
    View the complete SDK reference documentation
  </Card>
</CardGroup>