Skip to main content
This page lists every export of the Node package 0.4.3. Behaviour that differs in the next release is marked “from 0.4.4”. Node shows how to use them together.
The package is an ES module and needs Node 22 or later. It depends on Patchright, the driver it launches the browser with. Playwright, playwright-core, Puppeteer and puppeteer-core are optional peers. Install one to use it instead. Every function has a snake_case alias for code shared with the Python package: launch_context, launch_persistent_context, launch_process, ensure_binary, binary_info, discover_binary, discovery_report, clear_cache, load_catalogue, ensure_widevine and provision_widevine. translateOptions is an alias of toCanonicalLaunchConfig.

Launching

Every launch function resolves the options, looks up the locale and timezone of the connection’s exit, finds or downloads the browser, and starts it. They share the launch options.

launch

Returns the installed driver’s Browser. Under Patchright or Playwright, it is Playwright’s Browser with pages in a normal profile. The browser runs on a temporary profile that the driver deletes when the browser closes or the process exits. Under Puppeteer, it is Puppeteer’s Browser, whose newPage() already uses the normal profile. Under Patchright and Playwright these members differ from Playwright’s: Under every driver the result has three extra properties: launch() refuses userDataDir with ProfileResolutionError (code APOSTATE_USER_DATA_DIR_ON_LAUNCH). Use launchPersistentContext() to keep a profile. The declared return type is any, because the package cannot name both drivers’ types. Annotate the call site:

launchPersistentContext

Creates userDataDir if it does not exist and launches on it. Under Patchright and Playwright it returns the BrowserContext bound to the directory. Under Puppeteer it returns the Browser. The first launch stores a seed in userDataDir/apostate/identity, and every later launch without fingerprint presents the same machine. Seeds and identity has the details. The result carries apostateDriverName, apostateExecutablePath and apostateDiagnostics. A userDataDir in options that names another directory throws TypeError.

launchContext

Launches the browser and returns the context of its temporary profile. Under Playwright it is the persistent context, and under Puppeteer it is defaultBrowserContext(). It is a normal profile, not off-the-record. Closing it closes the browser. apostateBrowser holds the browser it came from.

launchProcess

Starts the browser with no driver attached. Use it to run the browser for a CDP client in another language, or with no automation at all. Raw binary shows it with --remote-debugging-port. It takes cwd, stdio (default "ignore") and env for the child process, and passes --user-data-dir itself when userDataDir is set. It gives the browser a Widevine CDM first, as the other launch functions do. With headless: false on a Linux host with no display, it starts Xvfb and stops it when the browser exits. From 0.4.4 it passes --no-first-run and --no-default-browser-check. In 0.4.3, add them to args for a headed launch on a new user data directory, or the browser can stop at a first-run dialog.

ApostateProcess

isConnected() is true until the process exits or close() is called. close() sends SIGTERM, waits up to 5 seconds, then sends SIGKILL.

Launch options

LaunchOptions is one object shared by every launch function. Several options have aliases, listed after the name. Under Patchright and Playwright the package always passes viewport: null, so the window sets the viewport. From 0.4.4 it also passes colorScheme: null, so a page reads the persona’s own prefers-color-scheme. In 0.4.3 Playwright emulates light. Call page.emulateMedia({ colorScheme: null }) there. See prefers-color-scheme in the 0.4.3 packages. From 0.4.4 it passes chromiumSandbox: true where the sandbox can start (macOS, Windows, and Linux as a regular user outside a container, with no seccomp filter and with user namespaces allowed), and a chromiumSandbox you pass is kept. Elsewhere Playwright passes --no-sandbox, and a headed first tab shows a 56-pixel bar for it. See A bar on the first tab. Other Playwright or Puppeteer launch options are not passed through. humanize: true throws UnsupportedFeatureError. A failed GeoIP lookup does not throw. It prints a warning starting with [Apostate], adds it to apostateDiagnostics.warnings, and sends no switch for the field it could not fill, so the persona uses en-US and the host’s timezone there. Errors shows the text.

Refused switches

These in args throw ProfileResolutionError before anything is downloaded:

driverInfo

Reports which driver a launch would use, without starting a browser:

DRIVERS

The drivers the package can launch with, in preference order: ["patchright", "playwright", "playwright-core", "puppeteer", "puppeteer-core"].

Binary management

The launch functions call these for you. Installation explains the cache, discovery and verification.

ensureBinary

Resolves to the path of a runnable browser executable. A string argument is a binaryPath. It looks in this order, and downloads only when nothing answers:
  1. executablePath or binaryPath, then APOSTATE_BINARY, taken as given. A path that holds no browser throws MissingBinaryError.
  2. This package’s own install in the cache, when its record still matches the executable’s SHA-256.
  3. The well-known locations: /Applications and ~/Applications on macOS, ~/.cache/apostate and /opt/apostate on Linux, %LOCALAPPDATA%\apostate on Windows. A browser found there is used only when an Apostate build record or catalogue sits beside it and it reports Chromium 152.0.7977.83.
  4. The release archive, downloaded, checked against the manifest’s SHA-256 before it is opened, and extracted into the cache. APOSTATE_KEEP_ARCHIVE keeps the verified archive.
It takes the launch options that concern the binary, plus force: true to reinstall even when a browser is found.
With proxy set and no download callback, the download throws BinaryDownloadError. A launch through a proxy on a machine without the browser fails this way. Run npx apostate install first.

binaryInfo

Resolves to what apostate info prints. It never throws for a missing release.

discoverBinary

The browser a launch would use without downloading, or null. It resolves to an object, not a path:

discoveryReport

The same search, with order, searched, found and rejected. Each entry of rejected has a path and a reason, such as no Apostate payload beside it (build/MANIFEST.lock or resources/profiles/catalogue.json) for a stock Chromium or reports Chromium <version>, not 152.0.7977.83 for another build.

clearCache

Deletes the cache directory. A string argument is a cacheDir. With target, it deletes only that target’s install for this Chromium version. With version, it deletes only that Chromium version’s directory.

verifyArtifact

Hashes archive (bytes, an ArrayBuffer or an async iterable of bytes) and throws BinaryIntegrityError unless it matches artifact.sha256.

expectedArtifactName

The release archive’s file name for a target, such as apostate-152.0.7977.83-linux-x64.tar.zst. It is exported but not declared in index.d.ts.

extractionFailureMessage

The message BinaryExtractionError carries when tar cannot read the archive. It is exported for the package’s tests and not declared in index.d.ts.

targetForHost

The release target for a Node platform and arch, by default this host’s. Throws UnsupportedPlatformError for a host with no build, such as an Intel Mac.

normalizeTarget

Returns the target in lower case, or this host’s target when none is given. Throws UnsupportedPlatformError for any name that is not one of the four targets.

Profiles

The browser composes the machine from the seed. These functions check options and profiles, and report which path a launch takes. How it works explains composition.

resolveProfile

Decides the launch path without starting anything:
source is native-composed for a seed or persona, host-inherited for host mode, and explicit-profile or explicit-file for a profile you wrote. platform is the persona the launch presents.

resolveLaunchConfig

The launch configuration after the GeoIP lookup, with locale, timezone and webrtc_ip filled in.

toCanonicalLaunchConfig

Checks the options and returns them in canonical form, without the lookup. Alias translateOptions.

validateProfile

Checks a profile against config/profile.schema.json and returns a copy. Throws ProfileResolutionError with the first problem, such as profile.cpu.cores is not part of the schema.

loadCatalogue

Reads the package’s catalogue, or the one at path, and returns its shape: catalogue_version, profile_schema_version, browser_build, model, anchors (the GPU families, each with id, platform, backend, members and rotation_status), axes and policies.

normalizePersona

Returns windows, macos, linux or null, and maps the aliases. Throws ProfileResolutionError for anything else.

hostPersona

The host’s own platform: windows, macos, linux, or null on another OS. This is not the persona a default launch presents on Linux.

defaultPersonaForHost

The persona a launch with no fingerprintPlatform presents: macos for macos, windows for windows and for linux. An unknown token is returned unchanged.

DEFAULT_PERSONA_BY_HOST

The frozen object defaultPersonaForHost() uses: { macos: "macos", windows: "windows", linux: "windows" }.

redactProxy

Removes the credential from a proxy: socks5://user:pass@proxy.example:1080 gives socks5://proxy.example:1080.

stableStringify

JSON with sorted keys and non-ASCII characters escaped, the form the package encodes --apostate-profile in.

Widevine

The browser ships without the Widevine CDM. A launch copies one from a local Google Chrome, or downloads it from Google’s component update service and checks its SHA-256, then keeps it in the cache directory it shares with the Python package. Widevine explains when you need this.

ensureWidevine

Gives the browser at executable a CDM if it has none, and resolves to the browser’s CDM directory. On Linux it also writes the CDM’s location into userDataDir. It resolves to null when executable is not inside an Apostate install or no CDM could be had, and never rejects.

provisionWidevine

Installs a CDM into this package’s browser now, replacing any it has, and rejects with WidevineError when none can be had. source is a WidevineCdm directory, with or without a version directory inside. platform_verified is false for windows-x64, where Widevine has not been tried. The Node CLI has no command for this. The Python CLI has apostate provision-drm.

Constants

Errors

Every error the package throws for its own reasons is an ApostateError with a code string and a details object. From 0.4.4 messages never contain a proxy credential. In 0.4.3 a BrowserLaunchError can echo the --apostate-profile value, which holds the credential base64-encoded. Invalid option types, such as a proxy that is not a URL, throw a plain TypeError. From 0.4.4 a timezone that is not an IANA zone name throws a RangeError. Errors lists the common messages and their fixes. ProfileResolutionError carries a specific code for each refusal: