👻 Puppeteer Ghost

• Bypass CDP, Proxy, webdriver detection
• Blocks WebRTC to prevent IP leaks
• Works exactly like regular Puppeteer - just import and use
• Supports proxy configuration with authentication

Installation

pnpm add puppeteer-ghost
# or
npm install puppeteer-ghost
# or
yarn add puppeteer-ghost

Quick Start

import puppeteer from 'puppeteer-ghost';

// Launch with optimized defaults - no configuration needed
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://www.browserscan.net/');

Default Configuration:

• headless: false - Browser window is visible by default
• defaultViewport: null - Uses full browser window size
• Anti-detection features automatically enabled
• Single tab behavior (no duplicate tabs)

Configuration

Custom Launch Options

/**
 * @type {import('puppeteer-ghost').GhostLaunchOptions}
 */
const launchOptions = {
    headless: true, // Run in headless mode
    args: ['--window-size=1920,1080'] // Custom browser arguments
};

const browser = await puppeteer.launch(launchOptions);

Advanced Configuration:

/**
 * @type {import('puppeteer-ghost').GhostLaunchOptions}
 */
const advancedOptions = {
    headless: false,
    defaultViewport: { width: 1920, height: 1080 },
    useSystemBrowser: true, // Use system Chrome (default: true)
    args: ['--disable-web-security', '--disable-features=VizDisplayCompositor'],
    proxy: {
        server: 'http://proxy.example.com:8080',
        username: 'user',
        password: 'pass'
    }
};

Browser Selection

By default, puppeteer-ghost uses your system's installed Chrome. You can switch to Puppeteer's bundled Chromium:

// Use system Chrome (default)
const browser = await puppeteer.launch({
    useSystemBrowser: true
});

// Use Puppeteer's bundled Chromium
const browser = await puppeteer.launch({
    useSystemBrowser: false
});

// Custom executable path (overrides useSystemBrowser)
const browser = await puppeteer.launch({
    executablePath: '/path/to/chrome'
});

Proxy Configuration

/**
 * @type {import('puppeteer-ghost').ProxyConfig}
 */
const proxyConfig = {
    server: 'http://proxy.example.com:8080',
    username: 'your-username', // optional
    password: 'your-password' // optional
};

const browser = await puppeteer.launch({
    proxy: proxyConfig
});

const page = await browser.newPage();
await page.goto('https://www.browserscan.net');

Extension Support

Load Chrome extensions with puppeteer-ghost:

import path from 'path';
import fs from 'fs';
const extensionPath = path.join(process.cwd(), 'extension-folder');
const browser = await puppeteer.launch({
    pipe: true, // required for extensions
    enableExtensions: [extensionPath]
});

API Reference

Core API

puppeteer.launch(options?)

Launches a new browser instance with built-in anti-detection capabilities.

/**
 * @param {GhostLaunchOptions} [options] - Launch configuration
 * @returns {Promise<GhostBrowser>} Enhanced browser instance
 */
const browser = await puppeteer.launch(options);

Example:

const browser = await puppeteer.launch({
    headless: false,
    proxy: {
        server: 'http://proxy.example.com:8080',
        username: 'user',
        password: 'pass'
    }
});

Type Definitions

GhostLaunchOptions

Extends Puppeteer's LaunchOptions with additional anti-detection properties:

interface GhostLaunchOptions extends LaunchOptions {
    /** Proxy configuration for routing traffic */
    proxy?: ProxyConfig;
    /** Use system browser instead of bundled Chromium (default: true) */
    useSystemBrowser?: boolean;
}

ProxyConfig

Configuration object for proxy settings:

interface ProxyConfig {
    /** Proxy server URL (http://host:port, https://host:port, socks5://host:port) */
    server: string;
    /** Authentication username (optional) */
    username?: string;
    /** Authentication password (optional) */
    password?: string;
}

GhostBrowser

Enhanced browser instance with anti-detection features:

interface GhostBrowser extends Browser {
    /** Creates a new page with anti-detection enabled */
    newPage(): Promise<GhostPage>;
}

GhostPage

Enhanced page instance with human-like interactions:

interface GhostPage extends Page {
    /** Click with randomized positioning and timing */
    click(selector: string, options?: MouseClickOptions): Promise<void>;
    /** Type with human-like delays between keystrokes */
    type(selector: string, text: string, options?: TypeOptions): Promise<void>;
}

TypeOptions

Options for the enhanced type method:

interface TypeOptions {
    /** Delay between keystrokes in milliseconds (default: random 10-50ms) */
    delay?: number;
}

Enhanced Methods

browser.newPage()

Creates a new page with anti-detection features automatically enabled.

/**
 * @returns {Promise<GhostPage>} Enhanced page instance
 */
const page = await browser.newPage();

Features enabled:

• WebRTC blocking to prevent IP leaks
• Proxy authentication (if configured)
• Human-like interaction methods

page.click(selector, options?)

Clicks on an element with human-like behavior including randomized positioning and timing delays.

/**
 * @param {string} selector - CSS selector to click
 * @param {MouseClickOptions} [options] - Click options
 * @returns {Promise<void>}
 */
await page.click('#submit-button', { button: 'left' });

page.type(selector, text, options?)

Types text into an element with human-like delays between keystrokes.

/**
 * @param {string} selector - CSS selector to type into
 * @param {string} text - Text to type
 * @param {TypeOptions} [options] - Typing options
 * @returns {Promise<void>}
 */
await page.type('#username', 'myusername', { delay: 100 });

License

ISC License - see the LICENSE file for details.

Issues

Found a bug? Open an issue or start a discussion.