Chromium on Vercel (serveless)

README.md

Chromium on Vercel (serverless)

This is an up-to-date guide on running Chromium in Vercel serverless functions in 2022. What you will read below is the result of two days of research, debugging, 100+ failed deployments, and a little bit of stress.

Getting started

Step 1: Install dependencies

Use chrome-aws-lambda that comes with Chromium pre-configured to run in serverless, and puppeteer-core due to the smaller size of Chromium distributive.

Turns out, choosing the right versions of dependencies is crucial. Newer versions of puppeteer-core ship larger Chromium distributive, which will exceed the 50MB function size limit on Vercel.

{
  "chrome-aws-lambda": "10.1.0",
  // Install v10 to have a smaller Chromium distributive.
  "puppeteer-core": "10.1.0"
}

If you feel adventerous and wish to update dependencies, start from updating chrome-aws-lambda. Its peer dependency on puppeteer-core will tell you the maximum supported version to use.

Why not Playwright?

Playwright comes with a larger Chromimum instance that would exceed the maximum allowed serverless function size limit of 50MB on Vercel (transitively, AWS).

Step 2: Write a function

The way you write your function does not matter: it may be a Node.js function, a part of your Next.js /api routes, or a Remix application. What matters on this stage is to launch Puppeteer with correct options.

// api/run.js
import edgeChromium from 'chrome-aws-lambda'

// Importing Puppeteer core as default otherwise
// it won't function correctly with "launch()"
import puppeteer from 'puppeteer-core'

// You may want to change this if you're developing
// on a platform different from macOS.
// See https://github.com/vercel/og-image for a more resilient
// system-agnostic options for Puppeteeer.
const LOCAL_CHROME_EXECUTABLE = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'

export default async function (req, res) {
  // Edge executable will return an empty string locally.
  const executablePath = await edgeChromium.executablePath || LOCAL_CHROME_EXECUTABLE
  
  const browser = await puppeteer.launch({
    executablePath,
    args: edgeChromium.args,
    headless: false,
  })
  
  const page = await browser.newPage()
  await page.goto('https://github.com')
  
  res.send('hello')
}

Step 3: Configure Vercel deployment

Choose Node.js 14.x

puppeteer-core@10 doesn't work well with newer versions of Node.js. The pinned version should be Node.js 14.

1. Go to your Vercel project.
2. Go to "Settings", then "General".
3. Locate the "Node.js version" section.
4. Select "Node 14".

In addition to configuring this on Vercel, make sure that your project's package.json doesn't have the engines.node property that would contradict your choise:

{
  "engines": {
    // If you have a newer version of Node in your package.json
    // Vercel will respect that and disregard what you've set
    // in your project's settings.
    "node": "14.x"
  }
}

Basically, you should not see this warning in your deployment logs:

Warning: Detected "engines": { "node": ">=14" } in your `package.json` that will automatically upgrade when a new major Node.js Version is released. Learn More: http://vercel.link/node-version

If you do, this means your Node.js version is not configured correctly and you should repeat this section.

---

References

• https://github.com/vercel/og-image, an old example of how Vercel used Chromium on the server to generate OG images.
• vercel/community#124, a large discussion on Puppeteer/Playwright in serverless functions.

---

Troubleshooting

Serverless function exceeds the maximum size limit of 50mb

Error: The Serverless Function "XYZ" is XX.YYmb which exceeds the maximum size limit of 50mb. Learn More: https://vercel.link/serverless-function-size

This means you're deploying a Chromium executable that's too large. Solve this by Installing the right dependency versions.

libnss3.so

Error while loading shared libraries: libnss3.so: cannot open shared object file: No such file or directory

This error means you're running an older/newer version of Node.js rather than Node.js 14. Solve this by Using the right Node.js version.

People on the web will suggest all sorts of things to tackle this, like installing libnss3.so manually, but fret not: it's solved by using the right version of Node.js.

---

If you found this helpful, consider Buying me a cup of coffee.

Okay I've managed to get it to work. I am on an M1 Mac!

https://github.com/gruckion/puppeteer-running-in-vercel <- Repo

You will need Chromium on your machine.

brew install --cask chromium If you run into issues use this guide here

TLDR?

1. Bundle size needs to be 50mb or less so use puppeteer-core for production.
2. Use @sparticuz/chromium for the chromium instance in Serverless environment
3. If you need less than 50mb then use @sparticuz/chromium-min and host the tz yourself.

// src/app/api/route.ts

import { NextRequest, NextResponse } from "next/server";
import puppeteerCore from "puppeteer-core";
import puppeteer from "puppeteer";
import chromium from "@sparticuz/chromium";

export const dynamic = "force-dynamic";

async function getBrowser() {
  if (process.env.VERCEL_ENV === "production") {
    const executablePath = await chromium.executablePath();

    const browser = await puppeteerCore.launch({
      args: chromium.args,
      defaultViewport: chromium.defaultViewport,
      executablePath,
      headless: chromium.headless,
    });
    return browser;
  } else {
    const browser = await puppeteer.launch();
    return browser;
  }
}

export async function GET(request: NextRequest) {
  const browser = await getBrowser();

  const page = await browser.newPage();
  await page.goto("https://example.com");
  const pdf = await page.pdf();
  await browser.close();
  return new NextResponse(pdf, {
    headers: {
      "Content-Type": "application/pdf",
    },
  });
}

// next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ['puppeteer-core', '@sparticuz/chromium'],
  }
};

export default nextConfig;

// package.json

{
  "name": "test-pdf-generate",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@sparticuz/chromium": "^123.0.0",
    "next": "14.1.4",
    "puppeteer": "^22.6.2",
    "puppeteer-core": "^22.6.2",
    "react": "^18",
    "react-dom": "^18"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "autoprefixer": "^10.0.1",
    "eslint": "^8",
    "eslint-config-next": "14.1.4",
    "postcss": "^8",
    "tailwindcss": "^3.3.0",
    "typescript": "^5"
  }
}

Credits

Unexpected token in EmulationManager.js when used with Next.js

puppeteer/puppeteer#11052 Sparticuz/chromium#147 (comment) https://nextjs.org/docs/app/api-reference/next-config-js/serverComponentsExternalPackages

Cannot spawn Chromium with custom executablePath on Apple M1

puppeteer/puppeteer#6634 Sparticuz/chromium#63 (comment)

This works perfectly 👍. Thank you for sharing this approach.

this worked for me: Sparticuz/chromium#147

This repo worked for me, use Nextjs with maxDuration 60 seconds:

=> hehehai/headless-try

@Himture Thanks for your example.

Mine looks nearly identical to that, and it works locally with vercel dev, but unfortunately when deployed to production on Vercel's free plan, I get this error:

Error: Failed to load page
    at c (/var/task/.next/server/pages/api/ig.js:1:906)
    at async K (/var/task/node_modules/next/dist/compiled/next-server/pages-api.runtime.prod.js:20:16545)
    at async U.render (/var/task/node_modules/next/dist/compiled/next-server/pages-api.runtime.prod.js:20:16981)
    at async r2.runApi (/var/task/node_modules/next/dist/compiled/next-server/server.runtime.prod.js:17:42119)
    at async r2.handleCatchallRenderRequest (/var/task/node_modules/next/dist/compiled/next-server/server.runtime.prod.js:17:36819)
    at async r2.runImpl (/var/task/node_modules/next/dist/compiled/next-server/server.runtime.prod.js:16:17074)
    at async r2.handleRequestImpl (/var/task/node_modules/next/dist/compiled/next-server/server.runtime.prod.js:16:16167)
    at async Server.<anonymous> (/var/task/___next_launcher.cjs:26:5)
    at async Server.<anonymous> (/opt/rust/nodejs.js:8:3933)

I still use Pages Router instead of App Router, though, since I prefer it. I wonder if that matters.

I see from @sekedus that https://github.com/hehehai/headless-try/blob/66cfd6294ac93bb1e1d563955582e0af62add48e/src/app/try/route.js uses App Router too.

Maybe I'll try forking that repo (and converting to TypeScript).

Thanks.

This repo worked for me, use Nextjs with maxDuration 60 seconds:

=> hehehai/headless-try

Works, thanks!

Okay I've managed to get it to work. I am on an M1 Mac!
https://github.com/gruckion/puppeteer-running-in-vercel <- Repo
You will need Chromium on your machine.
brew install --cask chromium If you run into issues use this guide here
TLDR?

1. Bundle size needs to be 50mb or less so use puppeteer-core for production.
2. Use @sparticuz/chromium for the chromium instance in Serverless environment
3. If you need less than 50mb then use @sparticuz/chromium-min and host the tz yourself.

// src/app/api/route.ts

import { NextRequest, NextResponse } from "next/server";
import puppeteerCore from "puppeteer-core";
import puppeteer from "puppeteer";
import chromium from "@sparticuz/chromium";

export const dynamic = "force-dynamic";

async function getBrowser() {
  if (process.env.VERCEL_ENV === "production") {
    const executablePath = await chromium.executablePath();

    const browser = await puppeteerCore.launch({
      args: chromium.args,
      defaultViewport: chromium.defaultViewport,
      executablePath,
      headless: chromium.headless,
    });
    return browser;
  } else {
    const browser = await puppeteer.launch();
    return browser;
  }
}

export async function GET(request: NextRequest) {
  const browser = await getBrowser();

  const page = await browser.newPage();
  await page.goto("https://example.com");
  const pdf = await page.pdf();
  await browser.close();
  return new NextResponse(pdf, {
    headers: {
      "Content-Type": "application/pdf",
    },
  });
}

// next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ['puppeteer-core', '@sparticuz/chromium'],
  }
};

export default nextConfig;

// package.json

{
  "name": "test-pdf-generate",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "@sparticuz/chromium": "^123.0.0",
    "next": "14.1.4",
    "puppeteer": "^22.6.2",
    "puppeteer-core": "^22.6.2",
    "react": "^18",
    "react-dom": "^18"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "autoprefixer": "^10.0.1",
    "eslint": "^8",
    "eslint-config-next": "14.1.4",
    "postcss": "^8",
    "tailwindcss": "^3.3.0",
    "typescript": "^5"
  }
}

Credits

Unexpected token in EmulationManager.js when used with Next.js

puppeteer/puppeteer#11052 Sparticuz/chromium#147 (comment) https://nextjs.org/docs/app/api-reference/next-config-js/serverComponentsExternalPackages

Cannot spawn Chromium with custom executablePath on Apple M1

puppeteer/puppeteer#6634 Sparticuz/chromium#63 (comment)

This works perfectly 👍. Thank you for sharing this approach.
thank you