Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
needle
✓ import needle from 'needle';
✗ const needle = require('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
✓ import needle from 'needle';
needle.get('url', callback);
✗ const { get } = require('needle');
The `.get` method is a property of the default `needle` export, not a named export. Ensure you import the default export first.
needle.post
✓ import needle from 'needle';
needle.post('url', data, options, callback);
✗ const { post } = require('needle');
Similar to `.get`, the `.post` method is accessed via the default `needle` export; it is not a named export.
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);
}
});
Debug
Known issues
gotchaWhen 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.fixIf 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.
affects: >=2.0.0
breakingVersion 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.fixCarefully test existing implementations after upgrading from pre-3.0.0 versions. Review Node.js documentation for changes in deprecated APIs if encountering unexpected behavior.
affects: >=3.0.0
gotchaBrotli 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.fixUpgrade 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.
affects: <10.16.0
gotchaThe `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.fixIf 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.
affects: <18.0.0 (for `iconv-lite` v0.7.0+)
gotchaFor 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.fixAlways 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. affects: >=2.0.0
Errors
Common errors & fixes
Error: Cannot find module 'needle'
The 'needle' package is not installed or not resolvable by the module loader in the current environment.
fixRun `npm install needle` or `yarn add needle` in your project directory to install the package.
ERR_REQUIRE_ESM
You are attempting to use `require('needle')` within an ECMAScript Module (ESM) context, which does not natively support CommonJS `require` calls without specific configuration.
fixUse `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
The remote server unexpectedly terminated the connection. This can be caused by various network issues, server-side misconfigurations, or aggressive firewall rules.
fixWhile 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]
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.
fixVerify 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.
Audit
Dependencies
iconv-literequiredRequired for streaming non-UTF-8 charset decoding.