@irithell-js/puppeteer-termux

Wrapper for the puppeteer module, specifically designed to resolve Chrome binary download failures and execution incompatibilities on Termux (Android). The package acts as a Drop-in Replacement, providing full compatibility with existing code and supporting both CommonJS and ESM.

Architecture and Solution

By default, the standard puppeteer module attempts to download a pre-compiled Google Chrome binary built for desktop Linux environments (glibc). This binary is entirely incompatible with Android's bionic architecture, causing the installation or execution to fail instantly on Termux.

The @irithell-js/puppeteer-termux resolves this bottleneck through an isolation and injection architecture:

1. Analytical Detection: Reads environment variables (process.env.PREFIX) to identify if the current runtime is Termux or a standard Linux server.
2. System Dependency Injection: Triggers the system package manager (pkg) to install the native Chromium browser directly from Termux repositories.
3. Hash Isolation: Calculates a unique MD5 identifier based on your project directory to create an aseptic build environment.
4. Binary Bypass: Installs Puppeteer while blocking the broken Chrome download via environment variables.
5. Monkey Patching: Automatically intercepts the puppeteer.launch() method at runtime, injecting the correct native executable path and essential Android safety flags.

Installation

npm install @irithell-js/puppeteer-termux

How to Use

Usage is identical to the original package. No refactoring is required in your current code; simply replace the import or require source. You do not need to manually pass the executable path or sandbox flags.

CommonJS

const puppeteer = require("@irithell-js/puppeteer-termux");

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.goto("[https://example.com](https://example.com)");
  console.log(await page.title());

  await browser.close();
})();

ESM

import puppeteer from "@irithell-js/puppeteer-termux";

const browser = await puppeteer.launch();
// Normal scraping operations...

Version Control (Update & Downgrade)

By default, the proxy automatically fetches the latest version of the original puppeteer package. If you need to pin a specific version, downgrade, or update, you can do so seamlessly without cluttering your project with broken binaries.

There are two methods to specify the target version:

Method 1: Via package.json (Recommended)

You can define the desired version using a custom irithell block in your project's root package.json. Note: Upon the first successful installation, the proxy features an Auto-Scaffolding mechanic that will automatically inject this block with the currently installed version for your convenience.

{
  "name": "your-project",
  "dependencies": {
    "@irithell-js/puppeteer-termux": "^1.0.1"
  },
  "irithell": {
    "puppeteerVersion": "24.42.0"
  }
}

Method 2: Via Environment Variable

You can also force a specific version directly from the terminal during installation:

PUPPETEER_VERSION=24.42.0 npm install @irithell-js/puppeteer-termux

Forcing the Engine Rebuild

If you change the version in your package.json after the initial installation, simply trigger the installer directly to safely destroy and rebuild the isolated engine:

node ./node_modules/@irithell-js/puppeteer-termux/dist/install.cjs

Internal Technical Features

Silent Failure Prevention

When package managers set the ignore-scripts = true restriction by default, installation in the postinstall lifecycle is blocked without emitting logs. This module features a handler that detects if the silent setup failed during your application's initialization and prevents a generic Node crash with instructions via logs.

Environment Migration (Cross-Environment Auto-Recovery)

When developing on Termux and later moving the entire project folder to a Linux VPS or Docker container, binary paths conflict. The proxy registers metadata containing the source architecture at the time of installation. During the first execution on the new platform, the module intercepts the discrepancy, destroys the original engine, and automatically initiates a new setup focused on the standard kernel.

Cleanup

If it is necessary to delete the isolated instances in Termux memory, the directory is located at:

~/.puppeteer_engines/