{"id":17272,"library":"httpcloak","title":"HTTPCloak Node.js Client","description":"HTTPCloak is a Node.js HTTP client specifically engineered for advanced browser fingerprint emulation across HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) protocols. It is designed to mimic real browser characteristics, including TLS and HTTP/2 fingerprints, to bypass sophisticated bot detection systems. The current stable version is 1.6.1, indicating an actively developed library that regularly incorporates updates necessary to counter evolving anti-bot technologies. While a formal release cadence isn't specified, libraries in this domain typically require frequent maintenance. Its key differentiators include comprehensive multi-protocol support and configurable browser presets, making it highly effective for web scraping, automation, and bypassing anti-bot measures.","status":"active","version":"1.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/sardanioss/httpcloak","tags":["javascript","http","http2","http3","quic","tls","fingerprint","browser","scraping","typescript"],"install":[{"cmd":"npm install httpcloak","lang":"bash","label":"npm"},{"cmd":"yarn add httpcloak","lang":"bash","label":"yarn"},{"cmd":"pnpm add httpcloak","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ES Modules, use named import. This is the primary class for creating HTTP sessions.","wrong":"const Session = require('httpcloak').Session; // Incorrect CommonJS access if in ESM context\nimport Session from 'httpcloak'; // Incorrect default import","symbol":"Session","correct":"import { Session } from 'httpcloak';"},{"note":"Use object destructuring for CommonJS environments. The library primarily exports named members.","wrong":"import { Session } from 'httpcloak'; // Will throw 'ERR_REQUIRE_ESM' in CommonJS environment","symbol":"Session (CommonJS)","correct":"const { Session } = require('httpcloak');"},{"note":"For TypeScript projects, explicitly import types using `import type` to ensure they are removed during compilation.","wrong":"import { SessionOptions } from 'httpcloak'; // Incorrect if only importing the type, may cause runtime issues if SessionOptions is not a runtime value","symbol":"SessionOptions (TypeScript Type)","correct":"import type { SessionOptions } from 'httpcloak';"}],"quickstart":{"code":"import { Session } from 'httpcloak';\n\nasync function runHttpcloakExample() {\n  const session = new Session({\n    preset: 'chrome-latest', // Emulate the latest Chrome browser fingerprint\n    // You can also specify proxy, timeouts, etc. here\n    // proxy: 'http://username:password@proxy.example.com:8080',\n    // timeout: 15000\n  });\n\n  try {\n    console.log('Performing GET request to Cloudflare trace...');\n    const getResponse = await session.get('https://www.cloudflare.com/cdn-cgi/trace');\n    console.log('GET Status Code:', getResponse.statusCode);\n    console.log('GET Response Text:\\n', getResponse.text.slice(0, 200), '...'); // Log first 200 chars\n\n    console.log('\\nPerforming POST request to a mock API...');\n    const postResponse = await session.post('https://jsonplaceholder.typicode.com/posts', {\n      title: 'foo',\n      body: 'bar',\n      userId: 1,\n    }, {\n      'Content-Type': 'application/json' // Custom headers for the request\n    });\n    console.log('POST Status Code:', postResponse.statusCode);\n    console.log('POST Response JSON:', JSON.parse(postResponse.text));\n\n    console.log('\\nAttempting concurrent requests...');\n    const [res1, res2] = await Promise.all([\n      session.get('https://example.com/'),\n      session.get('https://httpbin.org/get')\n    ]);\n    console.log('Concurrent Request 1 Status:', res1.statusCode);\n    console.log('Concurrent Request 2 Status:', res2.statusCode);\n\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n  } finally {\n    console.log('\\nClosing HTTPCloak session...');\n    session.close(); // Essential for resource cleanup\n  }\n}\n\nrunHttpcloakExample();","lang":"typescript","description":"This quickstart demonstrates promise-based asynchronous usage of HTTPCloak, covering GET and POST requests, handling responses, and executing concurrent requests, while emphasizing proper session management with `session.close()`."},"warnings":[{"fix":"Always ensure `session.close()` is called in a `finally` block or equivalent cleanup mechanism after all requests associated with the session are completed. For streaming, `stream.close()` is also necessary.","message":"Failing to call `session.close()` can lead to resource leaks, including open sockets and memory, especially in long-running applications or when creating many sessions. Each `Session` instance manages its own network connections and state.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you are running a recent Node.js version (e.g., Node.js 18+ for best HTTP/3 stability). If encountering issues, test with HTTP/2 or HTTP/1.1 by explicitly setting `protocol: 'http2'` or `protocol: 'http1'` in session options, or by disabling HTTP/3 in presets if possible.","message":"HTTP/3 support might require specific Node.js versions (Node.js 14+ is listed, but specific HTTP/3 features might be more robust in newer versions) and could be sensitive to underlying operating system QUIC implementations. Connection failures or unexpected behavior might occur if the environment is not fully compatible.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `const { Session } = require('httpcloak');` for CommonJS and `import { Session } from 'httpcloak';` for ES Modules to correctly import the Session class.","message":"The library primarily uses named exports. Directly `require('httpcloak')` without destructuring in CommonJS, or `import Session from 'httpcloak'` in ESM (expecting a default export), will result in `undefined` or an error when trying to access `Session`.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import { Session } from 'httpcloak';` and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to use `require()` to import `httpcloak` in an ECMAScript Module (ESM) project, or when Node.js is running in ESM mode.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/httpcloak/dist/index.js"},{"fix":"Verify that `import { Session } from 'httpcloak';` (ESM) or `const { Session } = require('httpcloak');` (CJS) is used, and that you are creating an instance: `const session = new Session({...});`.","cause":"The `Session` class was not correctly imported or instantiated, leading to an attempt to call a method on an undefined or incorrect object.","error":"TypeError: session.get is not a function"},{"fix":"Ensure that `session.close()` is called only once, after all operations for that session are complete. If concurrent operations are intended, manage them with `Promise.all` before closing the session, or use separate sessions for distinct sets of operations.","cause":"Attempting to make a request or perform an action on an `httpcloak` session after `session.close()` has already been called.","error":"UnhandledPromiseRejectionWarning: Error: Session already closed or invalid state"}],"ecosystem":"npm","meta_description":null}