Needle HTTP Client

Common errors

• Error: Cannot find module 'needle'

  cause The 'needle' package is not installed or not resolvable by the module loader in the current environment.
  fix Run `npm install needle` or `yarn add needle` in your project directory to install the package.

• ERR_REQUIRE_ESM

  cause You are attempting to use `require('needle')` within an ECMAScript Module (ESM) context, which does not natively support CommonJS `require` calls without specific configuration.
  fix Use `import needle from 'needle';` instead of `const needle = require('needle');` when working in an ESM environment (e.g., in a `.mjs` file or a project with `"type": "module"` in `package.json`).

• Error: read ECONNRESET

  cause The remote server unexpectedly terminated the connection. This can be caused by various network issues, server-side misconfigurations, or aggressive firewall rules.
  fix While often transient, ensure robust error handling and retry mechanisms. Needle versions 3.1.0+ include fixes to silence these errors after connection close, but the underlying network issue might persist. Check server logs and network conditions. For persistent connections, consider adding `keepAlive: true` in options for multiple requests to the same host.

• Unsupported encoding: [encoding name]

  cause Needle relies on `iconv-lite` for non-UTF-8 character set decoding, and the specified encoding is either not recognized by `iconv-lite` or the `iconv-lite` version is incompatible with your Node.js runtime.
  fix Verify that the encoding name is correct and supported by `iconv-lite`. If using an older Node.js version (prior to 18), you might need to explicitly pin your `iconv-lite` dependency to a version older than `0.7.0` to ensure compatibility.

Warnings

• gotcha When using callbacks or Promises, Needle buffers the entire response body into `response.body`. If no callback is provided and you are streaming directly (e.g., `.pipe()`), `response.body` will be skipped. Ensure you handle `response.body` or the stream appropriately based on your usage pattern.
  Fix: If buffering is desired, ensure a callback is provided to `needle.get`/`post` or use the Promise API. If streaming, pipe the response to a writable stream or listen to 'data' events directly.
• breaking Version 3.0.0 introduced significant internal changes, including the removal of deprecated Node.js API usage and the replacement of `.pipe` calls with `stream.pipeline` internally. While public API changes were not explicitly documented as breaking for most users, code relying on specific internal Node.js deprecated APIs or subtle stream behaviors might require adjustments.
  Fix: Carefully test existing implementations after upgrading from pre-3.0.0 versions. Review Node.js documentation for changes in deprecated APIs if encountering unexpected behavior.
• gotcha Brotli decompression is only supported on Node.js versions 10.16.0 or above. If Needle receives a Brotli-encoded response on an earlier Node.js version, it will not be able to decompress it, potentially leading to unreadable response bodies.
  Fix: Upgrade Node.js to version 10.16.0 or higher to utilize Brotli compression. Ensure your deployment environment meets this minimum requirement if Brotli is critical for your application.
• gotcha The `iconv-lite` dependency, which Needle uses for streaming non-UTF-8 charset decoding, had a breaking change in its v0.7.0 and v0.8.0 releases, dropping support for Node.js versions prior to 18. If your project uses an older Node.js runtime and `npm` resolves `iconv-lite` to v0.7.0+ (or v0.8.0+), charset decoding might fail or produce errors.
  Fix: If you are on Node.js <18 and rely on non-UTF-8 decoding, you may need to explicitly pin your `iconv-lite` dependency to a version older than `0.7.0` (e.g., `<0.7.0`). Otherwise, upgrade your Node.js environment to version 18 or newer.
• gotcha For multipart form-data uploads, the `file` option within the data object expects a string path to the file on the local filesystem, not a Node.js `fs.ReadStream`. Needle handles opening and streaming the file internally from the provided path. Providing a stream directly might lead to unexpected behavior or errors.
  Fix: Always provide a string path to the local file (e.g., `{ file: '/path/to/my/image.png', content_type: 'image/png' }`) for the `file` option in multipart uploads.

Install

• npm install needle npm
• yarn add needle yarn
• pnpm add needle pnpm

Imports

• needle
  wrong:

  const needle = require('needle');

  correct:

  import needle from 'needle';

  For ESM, 'needle' is the default export, typically used with `import needle from 'needle';`. For CommonJS, use `const needle = require('needle');`. The imported 'needle' object is itself callable for Promise-based requests (e.g., `needle('put', ...)`) and exposes methods like `.get` and `.post`.
• needle.get
  wrong:

  const { get } = require('needle');

  correct:

  import needle from 'needle';
  needle.get('url', callback);

  The `.get` method is a property of the default `needle` export, not a named export. Ensure you import the default export first.
• needle.post
  wrong:

  const { post } = require('needle');

  correct:

  import needle from 'needle';
  needle.post('url', data, options, callback);

  Similar to `.get`, the `.post` method is accessed via the default `needle` export; it is not a named export.

Quickstart

Demonstrates a Promise-based POST request for JSON data and a callback-based GET request, including basic error handling and HTTPS agent options.

import needle from 'needle';
import https from 'https'; // Required for AgentOptions if using self-signed certs

const agent = new https.Agent({
  rejectUnauthorized: process.env.NODE_ENV === 'production' // Example TLS option
});

const data = {
  username: 'testuser',
  password: process.env.TEST_PASSWORD ?? 'securepassword123'
};

needle('post', 'https://httpbin.org/post', data, { json: true, agent: agent })
  .then(response => {
    if (response.statusCode === 200) {
      console.log('Request successful:', response.body.json);
    } else {
      console.error('Request failed with status:', response.statusCode);
    }
  })
  .catch(err => {
    console.error('An error occurred during POST request:', err.message);
  });

// Example using callback style for a GET request
needle.get('https://httpbin.org/get', { agent: agent }, (error, response) => {
  if (error) {
    console.error('GET request error:', error.message);
    return;
  }
  if (response.statusCode === 200) {
    console.log('GET successful:', response.body.json);
  } else {
    console.error('GET failed with status:', response.statusCode);
  }
});