Browser Automation in Next.js Serverless Functions

Run headless Chrome directly inside Next.js server actions and API routes using @sparticuz/chromium

• puppeteer-core . No external server needed -- Chrome runs in the same serverless function.

Dependencies

pnpm add @sparticuz/chromium puppeteer-core

Core Pattern

import puppeteer from "puppeteer-core"; import chromium from "@sparticuz/chromium"; import fs from "node:fs";

const CHROME_PATHS = [ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser", ];

function findLocalChrome(): string { for (const p of CHROME_PATHS) { if (fs.existsSync(p)) return p; } throw new Error( Chrome not found. Set CHROMIUM_PATH to your Chrome/Chromium binary., ); }

async function launchBrowser() { const isLambda = !!process.env.VERCEL || !!process.env.AWS_LAMBDA_FUNCTION_NAME;

const executablePath = isLambda ? await chromium.executablePath() : process.env.CHROMIUM_PATH || findLocalChrome();

const args = isLambda ? chromium.args : ["--no-sandbox", "--disable-setuid-sandbox"];

return puppeteer.launch({ args, executablePath, headless: true, defaultViewport: { width: 1280, height: 720 }, }); }

On Vercel, @sparticuz/chromium bundles a compatible Chromium binary automatically. Locally, the launcher falls back to the system Chrome installation or CHROMIUM_PATH .

Server Actions

Screenshot

"use server";

export async function takeScreenshot(url: string) { const browser = await launchBrowser(); try { const page = await browser.newPage(); await page.goto(url, { waitUntil: "networkidle2", timeout: 30_000 }); const title = await page.title(); const screenshot = await page.screenshot({ fullPage: true, encoding: "base64", }); return { ok: true, title, screenshot: screenshot as string }; } catch (err) { return { ok: false, error: err instanceof Error ? err.message : String(err) }; } finally { await browser.close(); } }

Accessibility Snapshot

"use server";

export async function takeSnapshot(url: string) { const browser = await launchBrowser(); try { const page = await browser.newPage(); await page.goto(url, { waitUntil: "networkidle2", timeout: 30_000 }); const title = await page.title(); const snapshot = await page.accessibility.snapshot(); return { ok: true, title, snapshot: JSON.stringify(snapshot, null, 2) }; } catch (err) { return { ok: false, error: err instanceof Error ? err.message : String(err) }; } finally { await browser.close(); } }

API Routes

// app/api/browse/route.ts import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) { const { url, action } = await req.json();

if (!url) { return NextResponse.json({ error: "Provide a 'url'" }, { status: 400 }); }

const browser = await launchBrowser(); try { const page = await browser.newPage(); await page.goto(url, { waitUntil: "networkidle2", timeout: 30_000 });

if (action === "screenshot") {
  const screenshot = await page.screenshot({ encoding: "base64" });
  return NextResponse.json({ screenshot });
}

if (action === "snapshot") {
  const snapshot = await page.accessibility.snapshot();
  return NextResponse.json({ snapshot });
}

return NextResponse.json(
  { error: "action must be 'screenshot' or 'snapshot'" },
  { status: 400 },
);

} finally { await browser.close(); } }

Environment Variables

Variable Required Description

CHROMIUM_PATH

Local dev only Path to Chrome/Chromium binary. Not needed on Vercel.

On Vercel, @sparticuz/chromium auto-detects the bundled binary. Locally, if Chrome is not in a standard location, set CHROMIUM_PATH .

Vercel Configuration

The @sparticuz/chromium binary is large (~50MB). Increase the serverless function's memory and timeout if needed:

// next.config.ts const nextConfig = { serverExternalPackages: ["@sparticuz/chromium"], }; export default nextConfig;

If the project lives in a monorepo subdirectory, set outputFileTracingRoot so the Chromium binary is included in the deployment:

import path from "node:path";

const nextConfig = { outputFileTracingRoot: path.join(import.meta.dirname, "../../"), serverExternalPackages: ["@sparticuz/chromium"], }; export default nextConfig;

Limitations

• Vercel serverless functions have a 50MB compressed size limit. @sparticuz/chromium fits within this but leaves limited room for other large dependencies.

• Function execution timeout is 10s on Hobby, 300s on Pro. Complex page loads may need the Pro plan.

• Each invocation launches a fresh browser. There is no session persistence between requests.

• For workflows that need persistent sessions, longer timeouts, or full Chrome (no size limits), use the Vercel Sandbox pattern instead (see the vercel-sandbox skill).

Example

See examples/demo/ in the agent-browser repo for a working app with both serverless and sandbox patterns, and a deploy-to-Vercel button.