HTTP Header Generator

Common errors

• Error: Cannot find module 'header-generator'

  cause Incorrect import path, missing `header-generator` from `package.json`, or trying to use CommonJS `require` in an ESM-only context without proper configuration.
  fix Ensure `header-generator` is listed in `dependencies` and installed (`npm install header-generator`). Use `import { HeaderGenerator } from 'header-generator';` for ESM/TypeScript projects. For older Node.js or CommonJS, `const { HeaderGenerator } = require('header-generator');`.

• TypeError: headerGenerator.getHeaders is not a function

  cause The `headerGenerator` variable was not correctly initialized as an instance of `HeaderGenerator` or was reassigned.
  fix Verify that `headerGenerator = new HeaderGenerator(...)` was called successfully before attempting to use `getHeaders()`.

• Property 'someUnknownOption' does not exist on type 'HeaderGeneratorOptions'

  cause Attempting to pass an unrecognized option to the HeaderGenerator constructor or `getHeaders` method when using TypeScript, indicating a type mismatch or invalid configuration.
  fix Consult the `HeaderGeneratorOptions` interface and documentation to ensure all options passed are valid. Remove or correct any misspelled or unsupported options.

Warnings

• gotcha The standalone 'apify/header-generator' GitHub repository is marked as deprecated. While the `header-generator` npm package remains active and receives updates (primarily for its underlying data models), it is now managed as part of the broader Apify `fingerprint-suite` project. Users are encouraged to refer to the `fingerprint-suite` documentation for the latest context and best practices.
  Fix: Always consult the main `fingerprint-suite` repository for overarching architecture and updated guidelines regarding `header-generator`'s usage.
• gotcha The `getHeaders()` method always generates a *random* set of headers from the possible options. Calling it multiple times with the same parameters will likely produce different header sets, which is by design for anti-fingerprinting, but might be unexpected if deterministic output is desired.
  Fix: Store the result of `getHeaders()` if you need to reuse the same set of headers. Do not assume repeated calls will yield identical results without explicit caching.
• gotcha The generated headers do not include request-dependent headers such as `Host`, `Content-Length`, `Cookie`, or `If-None-Match`. These headers are specific to the individual HTTP request and must be added by the user's HTTP client or application logic.
  Fix: Manually add request-specific headers to the generated object before sending an HTTP request. For example, `const fullHeaders = { ...generatedHeaders, Host: 'example.com', 'Content-Length': body.length };`
• gotcha The `httpVersion` option in `HeaderGeneratorOptions` significantly impacts the structure and content of the generated headers, as HTTP/1 and HTTP/2 requests use different header sets (e.g., HTTP/2 uses `:method`, `:authority`, `:scheme`, `:path` pseudo-headers).
  Fix: Ensure the `httpVersion` option matches the actual HTTP version used by your client to avoid sending malformed or incorrect headers.

Install

• npm install header-generator npm
• yarn add header-generator yarn
• pnpm add header-generator pnpm

Imports

• HeaderGenerator
  wrong:

  const { HeaderGenerator } = require('header-generator');

  correct:

  import { HeaderGenerator } from 'header-generator';

  While CommonJS `require` works in Node.js, modern TypeScript/ESM projects should use named imports. This is the primary class for generating headers.
• PRESETS
  wrong:

  import PRESETS from 'header-generator';

  correct:

  import { PRESETS } from 'header-generator';

  PRESETS is a named export object containing predefined configurations for common browser/OS combinations.
• HeaderGeneratorOptions
  wrong:

  import { HeaderGeneratorOptions } from 'header-generator';

  correct:

  import type { HeaderGeneratorOptions } from 'header-generator';

  This is a TypeScript type definition for the options object passed to the HeaderGenerator constructor or getHeaders method. It should be imported as a type.

Quickstart

Demonstrates initializing HeaderGenerator with options, generating headers with global and specific constraints, and using predefined PRESETS.

import { HeaderGenerator, PRESETS } from 'header-generator';

(async () => {
    // Initialize the generator with default constraints
    const headerGenerator = new HeaderGenerator({
        browsers: [
            { name: 'chrome', minVersion: 90 },
            { name: 'firefox', minVersion: 80 },
            'safari'
        ],
        devices: ['desktop', 'mobile'],
        operatingSystems: ['windows', 'macos', 'linux', 'android', 'ios'],
        locales: ['en-US', 'en', 'de-DE'],
        httpVersion: '2'
    });

    // Generate headers based on the global options (randomly selected from possibilities)
    const headers1 = headerGenerator.getHeaders();
    console.log('Generated Headers (default options):', headers1);

    // Generate headers with specific, overriding options for a single call
    const headers2 = headerGenerator.getHeaders({
        operatingSystems: ['linux'],
        devices: ['desktop'],
        locales: ['es-ES']
    });
    console.log('Generated Headers (Linux desktop, Spanish locale):', headers2);

    // Initialize with a preset for a common configuration
    const modernWindowsChromeGenerator = new HeaderGenerator(PRESETS.MODERN_WINDOWS_CHROME);
    const headers3 = modernWindowsChromeChromeGenerator.getHeaders();
    console.log('Generated Headers (Modern Windows Chrome preset):', headers3);

    // Headers are generated randomly, subsequent calls yield different results
    const headers4 = headerGenerator.getHeaders();
    console.log('Another set of Headers (randomized):', headers4);
})();