Migration Guide

Migrating to the v2 Node.js SDK

The Browserbase v2 Node.js SDK has been rewritten from the ground up and ships with a ton of new features and better support that we can’t wait for you to try. This guide is designed to help you maximize your experience with v2.

We hope this guide is useful to you; if you have any questions don’t hesitate to reach out to us at [e-mail] or by creating a new issue. We’ve written out specific guidelines on how to migrate each v1 method to v2 below. v2 also adds one-to-one mappings for every API endpoint, so you can incorporate new Browserbase features in your codebase with much less lift.

Breaking Changes

The v2 SDK is more flexible, easier to use, and has a more consistent API. It is also a lot more modular, meaning the majority of function calls have changed from browserbase.$thing$Do() to browserbase.$thing.$do(). For example:

// v1 SDK
await browserbase.listSessions();

// v2 SDK
await bb.sessions.list();

Deleted Methods

load, loadUrl, and screenshot have been fully removed in the v2 SDK. You can use the following example instead that encapsulates the same functionality using Playwright:

import { chromium } from "playwright-core";
import { Browserbase } from "@browserbasehq/sdk";

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

async function run() {
  // Create a session on Browserbase
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });

  // Connect to the remote session
  const browser = await chromium.connectOverCDP(session.connectUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0];

  // Execute Playwright actions on the remote browser tab
  await page.goto("https://news.ycombinator.com/");
  const pageTitle = await page.title();
  if (pageTitle !== "Hacker News") {
    throw new Error(`Page title is not 'Hacker News', it is '${pageTitle}'`);
  }
  await page.screenshot({ path: "screenshot.png" });

  await page.close();
  await browser.close();
  console.log(
    `Done! View replay at https://browserbase.com/sessions/${session.id}`,
  );
}

run().catch(console.error);

Updates to Common Workflows

Create Session

This is how you would create a session with the v1 SDK:

// v1 SDK
import { Browserbase, CreateSessionOptions } from "@browserbasehq/sdk";

const browserbase = new Browserbase({
  apiKey: BROWSERBASE_API_KEY,
  projectId: BROWSERBASE_PROJECT_ID,
});

const options: CreateSessionOptions = { extensionId: "123" };
await browserbase.createSession(options);

Now, you can create a session with the v2 SDK by calling the create method on sessions:

// v2 SDK
import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({
  apiKey: BROWSERBASE_API_KEY,
});

const session = await bb.sessions.create({
  projectId: BROWSERBASE_PROJECT_ID,
});

For more complex types, you can use the provided TypeScript types in the API reference:

// v2 SDK
import { Browserbase } from "@browserbasehq/sdk";
import { SessionCreateParams } from "@browserbasehq/sdk/resources";

const browserSettings: SessionCreateParams.BrowserSettings = {
  context: {
    id: contextId,
    persist: true,
  },
};

const session = await bb.sessions.create({
  projectId: BROWSERBASE_PROJECT_ID,
  extensionId: "some_extension_id",
  browserSettings,
});

Get Connect URL

In the v1 SDK, you could run browserbase.getConnectUrl() to create a new session and retrieve its connect url, or browserbase.getConnectUrl({ sessionId: someSession.id }) to retrieve the connect url for an existing session.

// v1 SDK
// To create a new session and connect to it
const connectUrl = await browserbase.getConnectUrl();

// To connect to an existing session
const connectUrl = await browserbase.getConnectUrl({
  sessionId: someSession.id,
});

In the v2 SDK, you can create a session and retrieve its connect url in a single call with bb.sessions.create(). Getting the connect url for an existing session is no longer supported.

// v2 SDK
const session = await bb.sessions.create({
  projectId: BROWSERBASE_PROJECT_ID,
});

const connectUrl = session.connectUrl;

Complete Session

v1 allowed you to complete a session by calling browserbase.completeSession():

// v1 SDK
await browserbase.completeSession({ sessionId: someSession.id });

In the v2 SDK, completing a session is done by updating its status to REQUEST_RELEASE:

// v2 SDK
await bb.sessions.update(sessionId, {
  status: "REQUEST_RELEASE",
  projectId: BROWSERBASE_PROJECT_ID!,
});

Reference for other methods

These methods have been rewritten for modularity and flexibility. As mentioned above, the pattern here is that the method has been renamed from browserbase.$thing$Do() to bb.$thing.$do().

List Sessions

// v1 SDK
const sessions = await browserbase.listSessions();

// v2 SDK
const sessions = await bb.sessions.list();

Get Session

// v1 SDK
const session = await browserbase.getSession("some_session_id");

// v2 SDK
const session = await bb.sessions.retrieve("some_session_id");

Get Session Recording

// v1 SDK
const recording = await browserbase.getSessionRecording(someSession.id);

// v2 SDK
const recording = await bb.sessions.recording.retrieve("some_session_id");

Get Session Downloads

Note: The parameter retryInterval is no longer supported. You can configure retries with the following syntax on initialization:

const bb = new Browserbase({
  apiKey: BROWSERBASE_API_KEY,
  maxRetries: 5,
});

Keep in mind, however, that this only affects the default retry behavior, which will only retry on 4xx/5xx errors. The remaining pattern still applies:

// v1 SDK
const downloads = await browserbase.getSessionDownloads(someSession.id);

// v2 SDK
const downloads = await bb.sessions.downloads.list("some_session_id");

Get Debug Connection URLs

// v1 SDK
const debugUrls = await browserbase.getDebugConnectionUrls(someSession.id);

// v2 SDK
const debugUrls = await bb.sessions.debug("some_session_id");

Get Session Logs

// v1 SDK
const logs = await browserbase.getSessionLogs(someSession.id);

// v2 SDK
const logs = await bb.sessions.logs.list("some_session_id");