Puppeteer Setup in pnpm Monorepo (Ubuntu)

Root Cause (common issues)

• Puppeteer not installed → npx puppeteer command not found
• Chrome never downloaded → path missing
• pnpm monorepo skips postinstall scripts (no auto browser download)

---

Step 1: Install Puppeteer

From the repo root (workspace-wide):

pnpm add -w puppeteer

Or scoped to a specific app only:

pnpm add puppeteer --filter @my-app/backend

---

Step 2: Install Chrome (pnpm way — don't use npx)

pnpm exec puppeteer browsers install chrome

Fallback if above fails:

pnpm dlx puppeteer browsers install chrome

Force re-install (useful in CI or after pnpm install):

pnpm exec puppeteer browsers install chrome --force

---

Step 3: Verify

ls ~/.cache/puppeteer/chrome/

ldd ~/.cache/puppeteer/chrome/linux-*/chrome-linux64/chrome | grep "not found"
# Should print nothing if all libs are present

---

Step 4: Install Ubuntu System Libraries

Ubuntu 22.04

sudo apt-get install -y \
  libnspr4 libnss3 libasound2 \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 \
  libatspi2.0-0 libxshmfence1

Ubuntu 24.04 (libasound2 renamed to libasound2t64)

sudo apt-get update
sudo apt-get install -y \
  libnspr4 libnss3 libasound2t64 \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 \
  libatspi2.0-0 libxshmfence1

---

Step 5: Runtime Config (required on EC2 / servers)

Always launch with sandbox disabled in server environments:

puppeteer.launch({
  headless: 'new',
  args: ['--no-sandbox', '--disable-setuid-sandbox'],
})

---

One-Shot Fix (copy-paste)

# Install puppeteer in workspace
pnpm add -w puppeteer

# Install Chrome
pnpm exec puppeteer browsers install chrome

# Install Ubuntu 24.04 system deps
sudo apt-get update
sudo apt-get update
sudo apt-get install -y \
  libnspr4 libnss3 libasound2t64 \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 \
  libatspi2.0-0 libxshmfence1

---

Turborepo Gotcha

pnpm in monorepos often skips postinstall scripts (especially in CI), so Chrome is never auto-downloaded after pnpm install. Always run the browser install step explicitly after deploying or setting up a new environment.