Impit Native Binary (Linux x64 GNU)

Common errors

• Error: Cannot find module '@apify/impit/binary_name_for_your_platform' or similar native module loading error.

  cause The `@apify/impit` package failed to locate or load the correct platform-specific binary (like `impit-linux-x64-gnu`). This often happens if the `postinstall` script failed, or if the `optionalDependencies` for the binary were not correctly resolved for your system.
  fix Try reinstalling the main package: `npm rebuild @apify/impit` or `npm install --force @apify/impit`. Ensure your system has `node-gyp` dependencies if building from source. For deployment, ensure the correct binary for your target platform is present or built.

• Error: Request timed out after Xms.

  cause The HTTP request initiated by Impit did not receive a response within the configured timeout period. This could be due to slow network, server unresponsiveness, or target website deliberately delaying responses for bot detection.
  fix Increase the `timeout` option in the `Impit` constructor or `fetch` call (e.g., `timeout: 60_000` for 60 seconds). Inspect the target website's behavior and consider implementing retry logic with exponential backoff. Ensure your proxy (if used) is responsive.

• Error: ETIMEDOUT (Connection timed out) or ECONNREFUSED (Connection refused)

  cause Indicates a network-level issue where Impit couldn't establish or maintain a connection to the target server or proxy. This might be a firewall issue, incorrect proxy configuration, or the target server being offline/unreachable.
  fix Verify network connectivity from the machine running Impit to the target. Double-check `proxyUrl` configuration for typos or incorrect credentials. Ensure any firewalls or security groups allow outbound connections on the necessary ports.

• Error: certificate verify failed

  cause The TLS/SSL certificate of the target server could not be verified, often encountered when using proxies that re-encrypt traffic, or when dealing with self-signed certificates. This results from untrusted certificates in the chain.
  fix For development or trusted environments (use with caution in production), you might need to disable TLS verification by setting a specific option in Impit, if available, or configuring the underlying `NODE_TLS_REJECT_UNAUTHORIZED='0'` (discouraged). The correct fix usually involves correctly configuring your proxy's CA certificates or adding the custom CA to your system's trust store.

Warnings

• breaking In version `0.9.1`, the internal handling of redirects and cookies shifted from Rust to JavaScript. While intended to fix high-concurrency segmentation faults, this fundamental change in core request processing might introduce subtle behavioral differences or new edge cases for complex scraping scenarios compared to previous versions. Users relying on very specific redirect or cookie behavior should re-verify functionality.
  Fix: Thoroughly test existing scraping flows when upgrading to `0.9.1` or later, especially those involving multiple redirects, intricate cookie management, or single-page applications. Consult the changelog for any specific migration notes.
• gotcha As a native Node.js module built with `napi-rs`, Impit's stability can occasionally be affected by memory management issues, particularly in high-concurrency environments or when interacting with Node.js `Buffer` objects. While versions `0.9.0` and `0.10.0` included fixes for double-free errors and AbortSignal listener leaks, developers should monitor memory usage and potential segmentation faults in stress tests.
  Fix: Ensure you are on the latest stable version of `@apify/impit`. Implement robust error handling and resource cleanup. If persistent issues occur, consider isolating Impit operations into worker threads or separate processes.
• gotcha The effectiveness of 'fingerprinting' and 'impersonation' relies on keeping the emulated browser/client profiles up-to-date with real-world browser behavior. As websites evolve their bot detection, Impit's built-in fingerprints might become stale, leading to increased detection and blocking. This requires continuous maintenance from the library developers and awareness from users.
  Fix: Regularly update to the latest `@apify/impit` version to benefit from updated fingerprints and anti-detection mechanisms. Monitor target website responses for changes in blocking patterns. Consider implementing custom headers or client profiles if default ones are insufficient.
• gotcha Native Node.js modules, including `impit-linux-x64-gnu`, can sometimes fail to install or load correctly due to missing system dependencies (like C/C++ build tools) or ABI incompatibilities between Node.js versions. This typically manifests as 'Cannot find module' or 'Failed to load native module' errors.
  Fix: Ensure your development and deployment environments have necessary build tools (e.g., `build-essential` on Linux). Verify that your Node.js version is compatible with the version specified in the package's `engines` field (`>= 10`). Consider using official Docker images or pre-built binaries where available to avoid build issues.

Install

• npm install impit-linux-x64-gnu npm
• yarn add impit-linux-x64-gnu yarn
• pnpm add impit-linux-x64-gnu pnpm

Imports

• Impit
  wrong:

  const Impit = require('@apify/impit');

  correct:

  import { Impit } from '@apify/impit';

  The primary class for instantiating the Impit client. While this entry describes a native binary, users interact with the main `@apify/impit` package, which dynamically loads the correct platform-specific binary.
• ImpitOptions

  import { Impit, type ImpitOptions } from '@apify/impit';

  Type definition for the client configuration options. Best imported as a type alongside the main Impit class for TypeScript projects.
• RequestInit

  import { Impit, type RequestInit } from '@apify/impit';

  The `RequestInit` type, extending standard Fetch API options, is used for per-request configuration. This package's `RequestInit` allows specific Impit options like `redirect` and `timeout`.

Quickstart

Demonstrates initializing the Impit client with a browser fingerprint and making a basic GET request to httpbin.org with custom headers, showcasing the `fetch` API and per-request redirect and timeout options.

import { Impit } from '@apify/impit';

async function fetchData() {
  const impit = new Impit({
    client: 'chrome_100', // Emulate Chrome 100 fingerprint
    // Other common options include:
    // proxyUrl: process.env.PROXY_URL ?? 'http://user:pass@proxy.example.com:8000',
    // followRedirects: true,
    // timeout: 30_000, // 30 seconds
  });

  try {
    console.log('Fetching data with Impit...');
    const response = await impit.fetch('https://httpbin.org/get', {
      headers: {
        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36',
        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9',
        'Accept-Encoding': 'gzip, deflate, br',
        'Accept-Language': 'en-US,en;q=0.9'
      },
      // Per-request options, e.g., to override instance-level redirect setting
      redirect: 'manual', // or 'follow', 'error'
      timeout: 10_000, // Per-request timeout of 10 seconds
    });

    if (response.ok) {
      const data = await response.json();
      console.log('Successfully fetched data:', data);
    } else {
      console.error(`Request failed with status: ${response.status} - ${response.statusText}`);
      const errorBody = await response.text();
      console.error('Response body:', errorBody);
    }
  } catch (error) {
    console.error('An error occurred during fetch:', error);
  }
}

fetchData();