Overview
Functions let you deploy your existing browser automation scripts to Browserbase’s serverless infrastructure. Instead of running scripts on your own servers, you can publish them as cloud functions that are invoked via API.
This guide shows you how to take an existing automation script and deploy it as a Function using your preferred framework.
Prerequisites
Before deploying, ensure you have:
- An existing TypeScript browser automation script using Stagehand, Playwright, or Puppeteer
- A Browserbase account with your API key and Project ID (available in Settings)
Create Function Scaffolding
First, initialize a new Functions project. This creates the directory structure, installs dependencies, and sets up the required configuration files.
Initialize Your Project
Run the following command to create a new functions project:pnpm dlx @browserbasehq/sdk-functions init my-functions-project
my-functions-project directory with:
- A configured
package.json with required dependencies
- A
tsconfig.json for TypeScript support
- A template
.env file for your credentials
- A starter
index.ts file with an example function
Enter the Project Directory
Configure Environment Variables
Open the .env file and add your Browserbase credentials:BROWSERBASE_PROJECT_ID=your_project_id
BROWSERBASE_API_KEY=your_api_key
Adapting Your Script
The key difference between running locally and deploying as a Function is how you connect to the browser. In a function, Browserbase automatically creates a session and provides the connection details through the context parameter.
Using the Function Context
Every Function receives a context object containing session information:
defineFn("my-function", async (context) => {
const { session } = context;
// session.id - The session ID
// session.connectUrl - CDP connection URL for Playwright/Puppeteer
});
Framework Integration
Choose your framework below to see how to adapt your existing script for deployment.
Stagehand
Playwright
Puppeteer
Stagehand is the recommended framework for Functions. Use env: "LOCAL" mode and pass the CDP connection URL from context.session.connectUrl via localBrowserLaunchOptions.Local Script:import { Stagehand } from "@browserbasehq/stagehand";
const stagehand = new Stagehand({
env: "BROWSERBASE",
});
await stagehand.init();
await stagehand.page.goto("https://example.com");
// Your automation logic...
import { defineFn } from "@browserbasehq/sdk-functions";
import { Stagehand } from "@browserbasehq/stagehand";
defineFn("my-stagehand-function", async (context) => {
const { session } = context;
const stagehand = new Stagehand({
env: "LOCAL",
localBrowserLaunchOptions: {
cdpUrl: session.connectUrl,
},
});
await stagehand.init();
await stagehand.page.goto("https://example.com");
// Your automation logic...
return { success: true };
});
Using env: "LOCAL" with localBrowserLaunchOptions.cdpUrl connects Stagehand directly to the browser session via CDP. You can still use other Stagehand options alongside this configuration. See the Stagehand documentation for all available configuration options. Connect to the browser session using Playwright’s CDP connection with the session.connectUrl.Local Script:import { chromium } from "playwright-core";
import { Browserbase } from "@browserbasehq/sdk";
const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY });
const session = await bb.sessions.create({
projectId: process.env.BROWSERBASE_PROJECT_ID,
});
const browser = await chromium.connectOverCDP(session.connectUrl);
const browserContext = browser.contexts()[0]!;
const page = browserContext.pages()[0]!;
await page.goto("https://example.com");
// Your automation logic...
import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";
defineFn("my-playwright-function", async (context) => {
const { session } = context;
const browser = await chromium.connectOverCDP(session.connectUrl);
const browserContext = browser.contexts()[0]!;
const page = browserContext.pages()[0]!;
await page.goto("https://example.com");
// Your automation logic...
return { success: true };
});
Connect to the browser session using Puppeteer’s WebSocket endpoint with the session.connectUrl.Local Script:import puppeteer from "puppeteer-core";
import { Browserbase } from "@browserbasehq/sdk";
const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY });
const session = await bb.sessions.create({
projectId: process.env.BROWSERBASE_PROJECT_ID,
});
const browser = await puppeteer.connect({
browserWSEndpoint: session.connectUrl,
});
const page = (await browser.pages())[0]!;
await page.goto("https://example.com");
// Your automation logic...
import { defineFn } from "@browserbasehq/sdk-functions";
import puppeteer from "puppeteer-core";
defineFn("my-puppeteer-function", async (context) => {
const { session } = context;
const browser = await puppeteer.connect({
browserWSEndpoint: session.connectUrl,
});
const page = (await browser.pages())[0]!;
await page.goto("https://example.com");
// Your automation logic...
return { success: true };
});
Testing Locally
Before deploying, test your function locally using the development server:
Invoke your function to verify it works:
curl -X POST http://127.0.0.1:14113/v1/functions/my-function/invoke \
-H "Content-Type: application/json"
The local development server creates real Browserbase sessions using your credentials. This ensures your function behaves the same locally and in production.
Deploying to Production
Once your function works locally, deploy it to Browserbase:
You’ll receive a function ID that you can use to invoke your deployed function:
curl --request POST \
--url https://api.browserbase.com/v1/functions/YOUR_FUNCTION_ID/invoke \
--header 'Content-Type: application/json' \
--header 'x-bb-api-key: YOUR_API_KEY' \
--data '{"params": {}}'
Learn More
For detailed information on passing parameters, best practices, and limitations, see the Functions feature documentation.
Next Steps
