Stagehand Next.js Quickstart

Stagehand Next.js Quickstart is a Next.js starter project from Browserbase for building AI browser agents with the Stagehand SDK (version 4.1.0), scaffoldable with the single command npx create-browser-app.

What is the Stagehand Next.js Quickstart?

It is a Next.js application template that wires the Stagehand browser-automation SDK into a working web agent demo. You supply two credentials — BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID — and the project launches a browser either through browserbase.launch() for cloud sessions or localBrowser.launch() for a local browser, then runs AI operations via Stagehand.create(). Its output is a running Next.js app whose demo navigates to https://docs.stagehand.dev/, extracts content with Zod v4 schemas, and follows the quickstart link on that page. The template is published by Browserbase, the company behind Stagehand and the Browserbase browser platform, and it can be deployed directly to Vercel.

What makes it stand out?

• Stagehand 4.1.0 SDK integration — browser creation is handled with browserbase.launch() or localBrowser.launch(), and AI operations with Stagehand.create().
• Browserbase Model Gateway — only BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are required; no separate OpenAI key is needed.
• Streaming demo route — the /api/stagehand POST route streams the session ID and debugger URL to the page while the demo runs, then closes both Stagehand and the browser when the run finishes or fails.
• Structured extraction with Zod v4 schemas — the returned data from extract() and observe() is schema-validated.
• Explicit model selection — Model Gateway picks the default model, but you can add a model object with a supported provider-prefixed modelName in stagehand.config.ts.
• Environment switching — setting browserConfig.env to "BROWSERBASE" in stagehand.config.ts moves the demo from a local browser to Browserbase cloud browsers.
• Custom .cursorrules — a project-supplied Cursor rules file intended to make writing Stagehand code with an AI editor easier.
• Mocked regression tests — pnpm typecheck, pnpm lint, pnpm test, and pnpm build are the validation scripts, and the tests mock Browserbase to cover locator fallback, failed actions, session streaming, and browser cleanup, including client disconnection.

Who should use it?

• Developers new to Stagehand: start from a runnable Next.js app instead of an empty repository, with the SDK version pinned and configuration already wired.
• AI agent builders: prototype a web agent that navigates a real site, extracts structured data, and streams its session status to the UI.
• Teams evaluating Browserbase: test cloud browser sessions and Model Gateway by flipping one config value rather than rewriting a launch layer.
• Full-stack Next.js developers: drop browser automation into a Next.js API route without setting up a separate backend.

What can you build with it?

• Agent prototyping: replace the demo target with your own URL to extract or observe elements on a live page and watch the run through the streamed debugger URL.
• Data extraction pipelines: define Zod v4 schemas, call extract(), and consume validated JSON from the /api/stagehand route.
• Cloud automation on Browserbase: set browserConfig.env to "BROWSERBASE" and route sessions through Browserbase browsers using your project credentials.

How does it work?

1. Clone or deploy the repository, then copy .example.env to .env and add BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID.
2. Run pnpm install && pnpm dev to start the app.
3. Optionally set browserConfig.env to "BROWSERBASE" and define a model object in stagehand.config.ts.
4. Send a POST request to /api/stagehand; the route streams the session ID and debugger URL while the demo runs against https://docs.stagehand.dev/.

FAQ

What credentials do I need to run this quickstart?

You need BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID, stored in a .env file copied from .example.env. Because the project uses the Browserbase Model Gateway, a separate OpenAI API key is not required.

Can it run browsers locally instead of on Browserbase?

Yes. Browser creation goes through either browserbase.launch() or localBrowser.launch(), and setting browserConfig.env to "BROWSERBASE" in stagehand.config.ts switches the demo to Browserbase sessions.

Which AI model does the template use by default?

The Model Gateway chooses the model automatically. To pin one, add a model object with a supported provider-prefixed modelName to stagehand.config.ts; the gateway authenticates with your Browserbase API key.

What does the included demo actually do?

The demo navigates to https://docs.stagehand.dev/, uses Zod v4 schemas and the data returned by extract() and observe(), and follows the quickstart link on that documentation page.

What tests ship with the project?

The regression suite mocks Browserbase and covers locator fallback, failed actions, session streaming, and browser cleanup — including cleanup when the client disconnects. Validation runs through pnpm typecheck, pnpm lint, pnpm test, and pnpm build.