Node.js SDK
All the features and utilities for fast Node.js development with Browserbase.
If you are working with Node.js, the official @browserbasehq/sdk package is the easiest way
to connect and act upon headless browsers running on Browserbase.
Basic usage
Here is an example using the Browserbase Node.js SDK to load and screenshot pages:
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK with `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
// environment variables
const browserbase = new Browserbase();
// Load a webpage
const rawHtml = await browserbase.load("https://www.browserbase.com");
// Text-only mode
const text = await browserbase.load("https://www.browserbase.com", {
textContent: true,
});
// Screenshot (returns bytes)
const result = await browserbase.screenshot("https://www.browserbase.com", {
textContent: true,
});
Installation
Configuration
Create a Browserbase client instance:
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK with `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
// environment variables
const browserbase = new Browserbase();
// Init the SDK with the `apiKey` and `projectId` options
const browserbase = new Browserbase({ apiKey: "xxx", projectId: "xxx" });
Parameters
options parameter is optional.Your Browserbase API Key.
If missing, will be loaded from process.env.BROWSERBASE_API_KEY.
Your Browserbase Project ID.
If missing, will be loaded from process.env.BROWSERBASE_PROJECT_ID.
A customSessions API Base URL.
A custom Connect API Base URL.
Load pages and take screenshots
load(url_or_urls, options)
Return the text or raw HTML from the given URL(s).
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK
const browserbase = new Browserbase();
// Load a webpage
const rawHtml = await browserbase.load("https://www.browserbase.com");
// Load multiple webpages (returns iterator)
const rawHtmls = browserbase.load([
"https://www.browserbase.com",
"https://docs.browserbase.com",
]);
for await (let rawHtml of rawHtmls) {
// ...
}
// Text-only mode
const text = await browserbase.load("https://www.browserbase.com", {
textContent: true,
});
Parameters
A valid URL or array of URLs.
options parameter is optional.Return text only or raw HTML.
A valid Session ID.
Enables Proxying.
Return type
If url is a string, a Promise<string> is returned.
If url is a
string[], a Generator is returned.
screenshot(url, options)
Return the Blob of a screenshot.
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK
const browserbase = new Browserbase();
const blob = await browserbase.screenshot("https://www.browserbase.com");
// Full page screenshot
const blob2 = await browserbase.screenshot("https://www.browserbase.com", {
fullPage: true,
});
Parameters
A valid URL.
options parameter is optional.Set to true to take a full-page screenshot.
A valid Session ID.
Enables Proxying.
Return type
More information on how to deal with Blob
here.
Connect with Playwright or Puppeteer
getConnectURL(options)
Returns a Connect API URL for Puppeteer or Playwright.
Parameters
options parameter is optional.A valid Session ID.
Enables Proxying.
Sessions, downloads and recordings
createSession(options)
Create a new Session.
import { Browserbase } from "@browserbasehq/sdk";
const browserbase = new Browserbase();
const { id: sessionId } = await browserbase.createSession({
browserSettings: {
fingerprint: { devices: ["mobile"] },
},
});
Parameters
options parameter is optional.A valid Project ID.
A valid Extension ID.
Return type
The returned Session object matches the Sessions API GET /v1/sessions/:id
endpoint response type.
getSession(sessionId)
Retrieve a Session.
import { Browserbase } from "@browserbasehq/sdk";
const browserbase = new Browserbase();
const { status } = await browserbase.getSession(
"fef4db93-9995-4147-be1c-27ebb0228ea6",
);
Parameters
A valid Session ID.
Return type
The returned Session object matches the Sessions API GET /v1/sessions/:id
endpoint response type.
listSessions()
Returns the list of Sessions.
import { Browserbase } from "@browserbasehq/sdk";
const browserbase = new Browserbase();
const sessions = await browserbase.listSessions();
Return type
The returned Session list matches the Sessions API GET /v1/sessions
endpoint response type.
getSessionDownloads(sessionId, filePath, retryInterval, retryCount)
Retrieve and save a Session’s downloads on disk.
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";
const browserbase = new Browserbase();
const { id: sessionId } = await browserbase.createSession();
const browser = await chromium.connectOverCDP(
browserbase.connectUrl({ sessionId }),
);
// ...navigate the page and take actions...
await browserbase.getSessionDownloads(sessionId, "downloads.zip");
During a Session, files are synced in real time; the size of your downloads might
affect their immediate availability through the /downloads endpoint.
The getSessionDownloads() method provides a retry mechanism to cope with this
use case.
Parameters
A valid Session ID.
A valid relative file path.
The time between each retry.
The number of retries.
getDebugConnectionURLs(sessionId)
Retrieve the Session Live View URLs.
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";
const browserbase = new Browserbase();
const { id: sessionId } = await browserbase.createSession();
const browser = await chromium.connectOverCDP(
browserbase.connectUrl({ sessionId }),
);
// ...navigate the page and take actions...
const { debuggerFullscreenUrl } =
await browserbase.getDebugConnectionURLs(sessionId);
Parameters
A valid Session ID.
Return type
An object with the following properties is returned:
The URL to access the fullScreen remote view of the Session.
The URL to access the visible viewport remote view of the Session.
getSessionRecording(sessionId)
Retrieve the Session Recordings, a collection of rrweb events like DOM changes and user actions.
import { Browserbase, SessionRecording } from "@browserbasehq/sdk";
import { EventType, IncrementalSource } from "@rrweb/types";
const browserbase = new Browserbase();
const events = await browserbase.getSessionRecording(
"fef4db93-9995-4147-be1c-27ebb0228ea6",
);
for (let event of events) {
if (
event.type &&
event.type === EventType.IncrementalSnapshot &&
event.data
) {
// Filter input and mouse interactions
if (
[
IncrementalSource.Input,
IncrementalSource.MouseInteraction,
IncrementalSource.MouseMove,
].includes(event.data.source)
) {
// ...
}
}
}
Parameters
A valid Session ID.
Return type
Find a complete example in our “Use the Session recordings API” guide.
Was this page helpful?