camoufox-js

A JavaScript/TypeScript port of Camoufox - an advanced anti-fingerprinting tool for Firefox automation. This library provides a complete Node.js wrapper that doesn't rely on Python scripts, offering native JavaScript performance and integration.

Note: This is a modified fork of apify/camoufox-js with additional features and improvements.

Features

• 🎭 Advanced Anti-Fingerprinting: Sophisticated browser fingerprint spoofing
• 🌍 GeoIP Integration: Automatic location-based configuration
• 🖱️ Human-like Behavior: Cursor movement humanization
• 🔧 Highly Configurable: Extensive customization options
• 📱 Cross-Platform: Support for Windows, macOS, and Linux
• 🚀 TypeScript Support: Full type definitions included
• 🎯 Playwright Integration: Built on top of Playwright for reliable automation

Installation

npm install camoufox

Quick Start

Basic Usage

import { Camoufox } from 'camoufox';

async function main() {
    // Launch Camoufox with default settings
    const browser = await Camoufox({
        headless: false
    });
    
    const page = await browser.newPage();
    await page.goto('https://example.com');
    
    // Your automation code here
    
    await browser.close();
}

main();

Advanced Configuration

import { Camoufox } from 'camoufox';

async function main() {
    const browser = await Camoufox({
        // Operating system fingerprint
        os: 'windows', // or 'macos', 'linux', or ['windows', 'macos']
        
        // GeoIP-based configuration
        geoip: true, // Auto-detect IP, or pass specific IP: '1.2.3.4'
        
        // Humanize cursor movement
        humanize: 1.5, // Max duration in seconds
        
        // Locale settings
        locale: ['en-US', 'en-GB'],
        
        // Proxy configuration
        proxy: {
            server: 'http://proxy.example.com:8080',
            username: 'user',
            password: 'pass'
        },
        
        // Block resources
        block_images: true,
        block_webrtc: true,
        
        // Custom screen constraints
        screen: {
            min_width: 1024,
            max_width: 1920,
            min_height: 768,
            max_height: 1080
        },
        
        // Firefox addons
        addons: ['ublock_origin'],
        
        // Custom fonts
        fonts: ['Arial', 'Times New Roman'],
        
        // Debug mode
        debug: true
    });
    
    const page = await browser.newPage();
    await page.goto('https://browserscan.net');
    
    await browser.close();
}

main();

API Reference

Main Functions

Camoufox(options: LaunchOptions): Promise<Browser>

Launches a new Camoufox browser instance with the specified options.

downloadBrowser(installDir?: PathLike): Promise<string>

Downloads and installs the Camoufox browser binaries.

downloadMMDB(): Promise<void>

Downloads the GeoIP database for location-based fingerprinting.

removeMMDB(): void

Removes the downloaded GeoIP database.

Launch Options

Option	Type	Description
os	string | string[]	Operating system for fingerprint generation
headless	boolean | 'virtual'	Run in headless mode (use 'virtual' for Xvfb on Linux)
geoip	string | boolean	IP-based geolocation configuration
humanize	boolean | number	Humanize cursor movement
locale	string | string[]	Browser locale settings
proxy	string | object	Proxy configuration
block_images	boolean	Block all images
block_webrtc	boolean	Block WebRTC
block_webgl	boolean	Block WebGL
screen	Screen	Screen dimension constraints
window	[number, number]	Fixed window size
addons	string[]	Firefox addons to load
fonts	string[]	Custom fonts to load
fingerprint	Fingerprint	Custom BrowserForge fingerprint
executable_path	string	Custom Firefox executable path
firefox_user_prefs	object	Firefox user preferences
args	string[]	Additional browser arguments
env	object	Environment variables
debug	boolean	Enable debug output

Command Line Interface

Camoufox-js includes a CLI tool for browser management:

# Download/update Camoufox binaries
npx camoufox fetch

# Remove Camoufox binaries
npx camoufox remove

# Test browser with a URL
npx camoufox test [url]

Examples

Web Scraping with Anti-Detection

import { Camoufox } from 'camoufox';

async function scrapeWithStealth() {
    const browser = await Camoufox({
        os: 'windows',
        geoip: true,
        humanize: true,
        block_images: true, // Faster loading
        addons: ['ublock_origin'] // Ad blocking
    });
    
    const page = await browser.newPage();
    
    // Navigate with human-like behavior
    await page.goto('https://example.com', {
        waitUntil: 'networkidle'
    });
    
    // Extract data
    const title = await page.title();
    console.log('Page title:', title);
    
    await browser.close();
}

Testing with Different Fingerprints

import { Camoufox } from 'camoufox';

async function testFingerprints() {
    const configs = [
        { os: 'windows', locale: 'en-US' },
        { os: 'macos', locale: 'en-GB' },
        { os: 'linux', locale: 'de-DE' }
    ];
    
    for (const config of configs) {
        const browser = await Camoufox(config);
        const page = await browser.newPage();
        
        await page.goto('https://browserscan.net');
        
        // Check fingerprint
        const userAgent = await page.evaluate(() => navigator.userAgent);
        console.log(`${config.os}: ${userAgent}`);
        
        await browser.close();
    }
}

Troubleshooting

Common Issues

1. Browser not found: Run npx camoufox fetch to download binaries
2. GeoIP errors: Ensure GeoIP database is downloaded with downloadMMDB()
3. Permission errors: Check file permissions in the installation directory
4. Proxy issues: Verify proxy configuration and connectivity

Debug Mode

Enable debug mode to see detailed configuration:

const browser = await Camoufox({
    debug: true,
    // ... other options
});

Requirements

• Node.js 16+
• Windows, macOS, or Linux
• Internet connection for initial setup

Related Projects

• Camoufox - Original Python implementation
• Playwright - Browser automation framework
• BrowserForge - Browser fingerprint generation

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions