Usage

Minimal example with stealth plugin

This is the canonical starting point. It replaces the standard puppeteer require with puppeteer-extra, registers the stealth plugin, then launches and navigates exactly as you would with vanilla Puppeteer.

const puppeteer = require('puppeteer-extra')
const StealthPlugin = require('puppeteer-extra-plugin-stealth')

// Register the stealth plugin before launch
puppeteer.use(StealthPlugin())

puppeteer.launch({ headless: true }).then(async browser => {
  const page = await browser.newPage()
  await page.goto('https://example.com')
  await page.screenshot({ path: 'screenshot.png' })
  await browser.close()
})

TypeScript / ESM import

import puppeteer from 'puppeteer-extra'
import StealthPlugin from 'puppeteer-extra-plugin-stealth'

puppeteer.use(StealthPlugin())

const browser = await puppeteer.launch({ headless: true })
const page = await browser.newPage()
await page.goto('https://example.com')
await browser.close()

Using multiple plugins together

const puppeteer = require('puppeteer-extra')
const StealthPlugin = require('puppeteer-extra-plugin-stealth')
const AdblockerPlugin = require('puppeteer-extra-plugin-adblocker')

puppeteer.use(StealthPlugin())
puppeteer.use(AdblockerPlugin({ blockTrackers: true }))

puppeteer.launch({ headless: true }).then(async browser => {
  const page = await browser.newPage()
  await page.goto('https://www.vanityfair.com')
  // Ads and trackers are blocked; stealth evasions are active
  await page.screenshot({ path: 'result.png' })
  await browser.close()
})

Multiple independent instances (addExtra)

When you need two separate puppeteer instances with different plugin sets, use addExtra() instead of puppeteer.use():

const { addExtra } = require('puppeteer-extra')
const vanillaPuppeteer = require('puppeteer')
const StealthPlugin = require('puppeteer-extra-plugin-stealth')

const stealthPuppeteer = addExtra(vanillaPuppeteer)
stealthPuppeteer.use(StealthPlugin())

// stealthPuppeteer and vanillaPuppeteer now coexist independently
const browser1 = await stealthPuppeteer.launch()
const browser2 = await vanillaPuppeteer.launch()

Debugging plugin hooks

Set the DEBUG environment variable to see all plugin lifecycle events:

DEBUG=puppeteer-extra,puppeteer-extra-plugin:* node myscript.js

How plugins work

Plugins implement one or more hook methods:

Hook	When it fires
beforeLaunch(options)	Before puppeteer.launch() resolves
afterLaunch(browser, options)	Immediately after the browser process starts
onBrowser(browser, options)	When a browser instance is available
onTargetCreated(target)	Each time a new target (tab, worker) is created
onPageCreated(page)	Each time a new page is created
onTargetChanged(target)	When a target URL changes
onTargetDestroyed(target)	When a target closes
onDisconnected()	When the browser disconnects