- 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
pnpm add puppeteer-ghost
# or
npm install puppeteer-ghost
# or
yarn add puppeteer-ghostimport 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/');const puppeteer = require('puppeteer-ghost');
// Launch with optimized defaults - no configuration needed
(async () => {
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 defaultdefaultViewport: null- Uses full browser window size- Anti-detection features automatically enabled
- Single tab behavior (no duplicate tabs)
/**
* @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'
}
};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'
});/**
* @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');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]
});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'
}
});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;
}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;
}Enhanced browser instance with anti-detection features:
interface GhostBrowser extends Browser {
/** Creates a new page with anti-detection enabled */
newPage(): Promise<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>;
}Options for the enhanced type method:
interface TypeOptions {
/** Delay between keystrokes in milliseconds (default: random 10-50ms) */
delay?: number;
}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
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' });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 });ISC License - see the LICENSE file for details.
Found a bug? Open an issue or start a discussion.