Impit JavaScript Bindings (Linux x64 Musl)

Common errors

• Segmentation fault

  cause High-concurrency usage of `impit-node` versions `<0.9.1` causing issues with internal Rust-based redirect/cookie handling.
  fix Upgrade `impit-node` to `0.9.1` or later to leverage JS-based redirect/cookie management, significantly improving stability.

• Memory Leak detected (e.g., during AbortSignal reuse)

  cause Listeners on `AbortSignal` instances were not properly cleaned up in `impit-node` versions `<0.10.0` when the signal was reused across multiple `fetch` calls.
  fix Upgrade `impit-node` to `0.10.0` or later, or ensure `AbortSignal` instances are not reused across `fetch` calls in older versions.

• TypeError: (0 , impit_node_1.fetch) is not a function

  cause Attempting to import `fetch` as a default export (`import fetch from 'impit-node';`) or using incorrect CommonJS `require` syntax. `fetch` is a named export.
  fix Use `import { fetch } from 'impit-node';` for ESM, or `const { fetch } = require('impit-node');` for CJS.

• Error: Bad argument: fingerprint is not a recognized type

  cause Using an unsupported, misspelled, or outdated fingerprint string in `ImpitClient` or `fetch` options. Newer fingerprints like `okhttp` or specific browser versions are added in later releases.
  fix Refer to the `impit-node` documentation for a list of currently supported fingerprint strings (e.g., `'chrome-100'`, `'firefox-99'`). Ensure your `impit-node` version is recent enough to support the desired fingerprint profile.

Warnings

• breaking High-concurrency usage in `impit-node` versions prior to `0.9.1` could lead to segmentation faults and instability, particularly due to internal handling of redirects and cookies within the Rust layer.
  Fix: Upgrade to `impit-node@0.9.1` or newer. This version significantly reworks redirect and cookie handling to occur in the JavaScript layer, resolving these stability issues.
• gotcha Memory leaks could occur in `impit-node` versions prior to `0.10.0` when `AbortSignal` instances were reused across multiple `fetch()` calls, due to uncleaned listeners.
  Fix: Upgrade to `impit-node@0.10.0` or newer to ensure proper `AbortSignal` listener cleanup and prevent memory leaks. If upgrading is not possible, avoid reusing `AbortSignal` instances or implement manual listener detachment.
• gotcha Prior to `impit-node@0.9.2`, it was not possible to explicitly remove impersonated headers (e.g., `Sec-Fetch-User`). Setting their value to an empty string would result in an empty header being sent, rather than the header being omitted entirely. This limited granular control over default impersonations.
  Fix: Upgrade to `impit-node@0.9.2` or newer. Now, passing an empty string (e.g., `{'Sec-Fetch-User': ''}`) in the `headers` option will correctly filter out the header before the request is sent.
• gotcha In `impit-node` versions before `0.9.0`, direct manipulation or handling of Node.js `Buffer` objects in certain scenarios could lead to double-free memory errors due to how `napi-rs` managed memory ownership.
  Fix: Upgrade to `impit-node@0.9.0` or newer. This version implements `BufferSlice` for safer `Buffer` handling, mitigating these memory corruption issues.
• gotcha The `redirect` option in `RequestInit` for per-request redirect control was introduced in `impit-node@0.12.0`. In older versions, redirect behavior was solely controlled by the client-level `followRedirects` setting, offering less flexibility.
  Fix: Upgrade to `impit-node@0.12.0` or newer to utilize the `redirect` option within `RequestInit` for fine-grained, per-request redirect management.

Install

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

Imports

• fetch
  wrong:

  import fetch from 'impit-node';

  correct:

  import { fetch } from 'impit-node';

  The `fetch` function provided by Impit is a named export, not a default export. While CommonJS `require` might work in some contexts, `impit-node` primarily promotes ESM `import` usage.
• ImpitClient
  wrong:

  const ImpitClient = require('impit-node').ImpitClient;

  correct:

  import { ImpitClient } from 'impit-node';

  The `ImpitClient` class is a named export, used for creating instances with shared configurations. ESM `import` is the recommended way to use it.
• RequestInit
  wrong:

  import { RequestInit } from 'impit-node';

  correct:

  import { type RequestInit } from 'impit-node';

  This is Impit's custom `RequestInit` type definition, which extends the standard Fetch API `RequestInit`. Use `import type` for type-only imports to ensure proper tree-shaking and avoid potential runtime issues.

Quickstart

Demonstrates how to initialize an `ImpitClient` with global options and perform requests, along with using the standalone `fetch` function for per-request configuration, including fingerprinting, custom headers, and timeout options.

import { ImpitClient, fetch, RequestInit } from 'impit-node';

async function runImpitExample() {
  const impitClient = new ImpitClient({
    // Emulate a specific browser fingerprint for advanced anti-bot detection
    fingerprint: 'chrome-100',
    // Global timeout for all requests made with this client
    timeout: 30000, // 30 seconds
    // Whether to follow redirects globally
    followRedirects: true,
  });

  try {
    console.log('--- Using ImpitClient instance ---');
    const clientResponse = await impitClient.fetch('https://httpbin.org/get', {
      headers: {
        'X-Client-Header': 'ImpitClient',
      },
      // Per-request redirect override (new in 0.12.0)
      redirect: 'manual'
    } as RequestInit);

    if (clientResponse.ok) {
      const data = await clientResponse.json();
      console.log('Client response status:', clientResponse.status);
      console.log('Client response headers (content-type):', clientResponse.headers.get('Content-Type'));
      console.log('Client response data (origin):', data.origin);
    } else {
      console.error('Client request failed:', clientResponse.status, await clientResponse.text());
    }

    console.log('\n--- Using direct fetch function ---');
    const directResponse = await fetch('https://httpbin.org/anything', {
      fingerprint: 'firefox-99', // Can specify fingerprint per-request
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Direct-Fetch-Header': 'ImpitGlobalFetch',
      },
      body: JSON.stringify({ message: 'Hello from Impit direct fetch!' }),
      // Disable timeout for this specific request (check impit-node changelog for exact version)
      timeout: null
    } as RequestInit);

    if (directResponse.ok) {
      const data = await directResponse.json();
      console.log('Direct fetch response status:', directResponse.status);
      console.log('Direct fetch data (method):', data.method);
      console.log('Direct fetch data (json):', data.json);
    } else {
      console.error('Direct fetch failed:', directResponse.status, await directResponse.text());
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

runImpitExample();