puppeteer-obscura

Drop-in Puppeteer browser powered by Obscura — no Chrome required.

Automatically downloads and launches the Obscura headless browser, then wires it up to puppeteer-core via CDP. Same Puppeteer API you already know, without the 300 MB Chrome baggage.

Why Obscura?

| Metric | Obscura | Headless Chrome | |---------------|-------------|-----------------| | Memory | ~30 MB | 200+ MB | | Binary size | ~70 MB | ~300 MB | | Anti-detect | ✅ built-in | ❌ none | | Page load | ~85 ms | ~500 ms | | Startup | instant | ~2s | | Puppeteer | ✅ | ✅ |

Installation

npm install puppeteer-obscura
# The Obscura binary is downloaded automatically on postinstall

Usage

import { launch } from "puppeteer-obscura";

const browser = await launch({ stealth: true });
const page    = await browser.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close(); // disconnects puppeteer and kills Obscura

API

launch(opts?): Promise<Browser>

Installs Obscura if needed, starts the CDP server, and returns a puppeteer-core Browser ready to use.

| Option | Type | Default | Description | |--------------------|-----------|---------|--------------------------------------------------| | port | number | 9222 | CDP port exposed by Obscura | | stealth | boolean | false | Enables Obscura's built-in anti-detection mode | | puppeteerOptions | object | {} | Extra options forwarded to puppeteer.connect() |

installObscura(): Promise<string>

Downloads and installs the binary without launching a browser. Useful for pre-installing in a Dockerfile or CI pipeline.

import { installObscura } from "puppeteer-obscura";

await installObscura();

Supported platforms

| OS | Arch | |---------|-----------------------| | Linux | x64 | | Linux | arm64 | | macOS | Apple Silicon (arm64) | | macOS | Intel (x64) | | Windows | x64 |

Development

npm install       # also downloads the Obscura binary
npm run build     # tsc → dist/