Camoufox JS

After installing the package, you must download the Camoufox browser binaries using the fetch command. By default, these are stored in the per-user cache directory ($XDG_CACHE_HOME/camoufox or ~/.cache/camoufox on Linux).

To install the browser to a custom location (recommended for containers or CI environments), set the CAMOUFOX_INSTALL_DIR environment variable.

# Default installation
npx camoufox-js fetch

# Custom installation location
CAMOUFOX_INSTALL_DIR=/opt/camoufox npx camoufox-js fetch

Install the JavaScript client for Camoufox using npm:

npm install camoufox-js

The locale.ts module provides utilities for handling language, region, and script settings, as well as deriving geolocation data from IP addresses. This is useful for configuring browser fingerprinting to match a specific target audience or location.

Key Concepts

• Locale: Represents a combination of language, region, and optionally a script (e.g., en-US).
• Geolocation: Represents physical location data (longitude, latitude, timezone) paired with a Locale.
• Statistical Selection: When providing only a language or a region, the library uses statistical data (from Unicode territory information) to pick a likely matching pair (e.g., providing en might result in en-US or en-GB based on population weights).

Usage

You can normalize locale strings, handle single or multiple locales, and resolve geolocation from an IP address.

If you need to use additional Playwright launch options or override Camoufox defaults, use the launchOptions function. This function returns an object that can be spread into a standard firefox.launch() call from playwright-core.

import { launchOptions } from 'camoufox-js';
import { firefox } from 'playwright-core';

// Ensure you have run `npx camoufox-js fetch` first
const browser = await firefox.launch({
    ...await launchOptions({
        // Camoufox options
    }),
    // other Playwright options, overriding the Camoufox options
});
            
const page = await browser.newPage(); // `page` is a Playwright Page instance

The simplest way to launch a Playwright-controlled Camoufox instance is by calling the Camoufox function. This returns a browser instance where the page object is a standard Playwright Page instance.

import { Camoufox } from 'camoufox-js';

// Ensure you have run `npx camoufox-js fetch` first
const browser = await Camoufox({
    // custom camoufox options
});
            
const page = await browser.newPage(); // `page` is a Playwright Page instance

You can run Camoufox as a remote websocket server. This allows access from other devices or other programming languages that support the Playwright API. Use launchServer to start the server and firefox.connect() to connect to it via its websocket endpoint.

import { launchServer } from 'camoufox-js';
import { firefox } from 'playwright-core';

// Ensure you have run `npx camoufox-js fetch` first
const server = await launchServer({ port: 8888, ws_path: '/camoufox' });
const browser = await firefox.connect(server.wsEndpoint());

const page = await browser.newPage();

// ...
// Use your browser instance as usual
// ...

await browser.close();  
await server.close(); // Close the server when done

Use confirmPaths to ensure that a list of addon directory paths are valid and ready for use. A valid addon path must:

1. Exist on the filesystem.
2. Be a directory.
3. Contain a manifest.json file (indicating the addon is properly extracted).

If any path fails these checks, the function throws an InvalidAddonPath error.

import { confirmPaths } from 'camoufox-js';

try {
  confirmPaths(['./addons/ublock-origin', './addons/custom-addon']);
} catch (error) {
  console.error('One or more addon paths are invalid:', error);
}

Use the following functions to validate IP address formats:

• validIPv4(ip: string | false): Returns true if the string is a valid IPv4 address.
• validIPv6(ip: string | false): Returns true if the string is a valid IPv6 address.
• validateIP(ip: string): Validates that a string is either a valid IPv4 or IPv6 address. Throws InvalidIP if the validation fails.

import { validIPv4, validIPv6, validateIP } from "camoufox-js";

validIPv4("192.168.1.1"); // true
validIPv6("2001:db8::1"); // true

try {
  validateIP("not-an-ip");
} catch (e) {
  // Throws InvalidIP
}

If you have a specific addon URL, use downloadAndExtract to fetch the file and unzip it to a target directory. This is useful for managing custom extensions manually.

Parameters:

• url: The direct URL to the addon file (e.g., an .xpi file).
• extractPath: The local directory where the addon should be extracted.
• name: A label used for logging progress during download and extraction.

import { downloadAndExtract } from 'camoufox-js';

await downloadAndExtract(
  'https://example.com/my-addon.xpi',
  './local/path/to/addon',
  'my-custom-addon'
);