Registry / http-networking / node-fetch-native-with-agent

node-fetch-native-with-agent

library1.7.2jsnpmunverified

node-fetch-native-with-agent is a fork of node-fetch-native that provides a universal `fetch` implementation for Node.js, designed for compatibility across various Node.js versions and environments. It intelligently prefers the native `fetch` global (backed by Undici) when available in newer Node.js versions and falls back to a bundled `node-fetch v3` implementation for older versions, all while supporting both CommonJS (`require`) and ESM (`import`). Its key differentiator is the compact size, zero direct dependencies for the core, and robust built-in proxy support via custom agents, which is a common challenge with native `fetch` in Node.js. The current stable version is 1.7.2, with minor fixes released as needed, indicating an active maintenance cadence. It also includes polyfill capabilities to make `fetch` globally available. This package aims to solve the `node-fetch` v2 vs v3 dependency conflicts and the lack of straightforward proxy support with Node.js's native `fetch`.

http-networking

npm install node-fetch-native-with-agent

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-FETCH-NATIVE-

node-fetch-native-with-agent

http-networkingjavascriptv1.7.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetch

✓ import fetch from 'node-fetch-native-with-agent';

✗ const fetch = require('node-fetch-native-with-agent').default;

This is the primary way to import the default `fetch` function. For CommonJS, `require` returns the `fetch` function directly, not an object with a `default` property.

{ fetch, Headers, Request }

✓ import { fetch, Headers, Request } from 'node-fetch-native-with-agent';

✗ const { fetch, Headers, Request } = require('node-fetch-native-with-agent/node');

Named exports for `fetch` and related Web API globals (Blob, FormData, Headers, Request, Response, AbortController) are available in both ESM and CommonJS. Ensure you're not trying to destructure from the `/node` path unless explicitly forcing the non-native version.

Polyfill

✓ import 'node-fetch-native-with-agent/polyfill';

✗ require('node-fetch-native-with-agent'); // Does not polyfill

To make `fetch` globally available, you must explicitly import or require the polyfill path. This is generally not recommended for library authors to avoid global pollution.

Force Non-Native

✓ import fetch from 'node-fetch-native-with-agent/node';

✗ import fetch from 'node-fetch-native-with-agent'; // May use native fetch

To explicitly use the `node-fetch` implementation and bypass Node.js's native `fetch` (e.g., for compatibility issues or specific features not present in native), import from the `/node` subpath. Alternatively, set the `FORCE_NODE_FETCH` environment variable.

Demonstrates basic `fetch` usage with `node-fetch-native-with-agent`, including how to configure and use an `HttpsProxyAgent` for HTTP/S proxy support. It explicitly shows agent creation, although the library also respects `HTTP_PROXY`/`HTTPS_PROXY` environment variables automatically.

import fetch from 'node-fetch-native-with-agent'; import { HttpsProxyAgent } from 'https-proxy-agent'; async function fetchDataWithAgent() { const proxyUrl = process.env.HTTPS_PROXY || 'http://localhost:8080'; // Replace with your proxy URL let agent; // Check if a proxy URL is provided if (proxyUrl) { // node-fetch-native-with-agent automatically handles Undici/non-Undici agent types. // For explicit agent usage, especially with older Node.js versions or specific configurations, // you might pass a compatible agent instance. // This example shows how you might set up an HttpsProxyAgent, which the library then uses. console.log(`Using proxy: ${proxyUrl}`); agent = new HttpsProxyAgent(proxyUrl); } else { console.log('No proxy configured. Fetching directly.'); } try { const response = await fetch('https://jsonplaceholder.typicode.com/todos/1', { agent: agent // The library will pick up the agent automatically if env vars are set // but explicit passing is also supported for custom agents. }); if (!response.ok) { throw new Error(`HTTP error! Status: ${response.status}`); } const data = await response.json(); console.log('Fetched Data:', data); } catch (error) { console.error('Error fetching data:', error); } } fetchDataWithAgent();

Debug

Known issues

gotchaWhen using `node-fetch-native-with-agent` in a CommonJS context, attempting to `require('node-fetch-native-with-agent').default` will result in `undefined` or an error, as the main export *is* the `fetch` function itself, not an object containing a `default` property.

fix

For CommonJS, use `const fetch = require('node-fetch-native-with-agent');` directly. For named exports, use `const { fetch, Headers } = require('node-fetch-native-with-agent');`.

affects: >=1.0.0

gotchaThe package transparently uses Node.js's native `fetch` implementation (backed by Undici) if available and enabled. While generally beneficial for performance and standards compliance, this means the behavior might subtly differ from the bundled `node-fetch` fallback, particularly concerning certain options or edge cases. If unexpected behavior occurs, consider explicitly forcing the non-native version.

fix

To force the use of the non-native `node-fetch` implementation, either set the environment variable `FORCE_NODE_FETCH=1` or import from `node-fetch-native-with-agent/node` (e.g., `import fetch from 'node-fetch-native-with-agent/node';`).

affects: >=1.0.0

deprecatedWhile polyfilling `globalThis.fetch` is supported via `node-fetch-native-with-agent/polyfill`, it is generally discouraged for library authors to avoid global side effects and potential conflicts with other libraries or environments that might also attempt to polyfill `fetch` or use their own native implementation.

fix

Prefer explicit imports of `fetch` (e.g., `import fetch from 'node-fetch-native-with-agent';`) within your modules rather than relying on global polyfilling, especially when authoring libraries.

affects: >=1.0.0

gotchaProxy support relies on the `http_proxy`/`https_proxy` environment variables or explicitly passing an agent instance. If a proxy is configured via environment variables but `node-fetch-native-with-agent` doesn't seem to use it, ensure the variable names are correctly cased (`HTTP_PROXY`, `HTTPS_PROXY` are also checked, in addition to lowercase) and that no explicit `agent` option is overriding it.

fix

Verify that `HTTP_PROXY` or `HTTPS_PROXY` (or their lowercase counterparts) environment variables are correctly set before application startup. If passing a custom agent, ensure it's compatible and correctly instantiated (e.g., `new HttpsProxyAgent(proxyUrl)`).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , _nodeFetchNative.default) is not a function

Attempting to use CommonJS `require` syntax as if it were an ESM default import or incorrectly bundling CJS code.

fix

If in CommonJS, use `const fetch = require('node-fetch-native-with-agent');`. If using a bundler, ensure it correctly handles CommonJS to ESM interop or configure it to resolve `node-fetch-native-with-agent` correctly for your target environment.

Error: The 'agent' option is not supported for native fetch.

This specific error string is unlikely with this package as it's designed to *add* agent support to native fetch. However, similar issues related to `agent` options might arise if an incompatible or outdated agent package is used with the underlying Undici implementation.

fix

Ensure you are using a compatible proxy agent like `https-proxy-agent` or allowing `node-fetch-native-with-agent` to handle proxy setup automatically via environment variables. The package is specifically built to bridge this gap.

ReferenceError: fetch is not defined

The `fetch` function was not imported or the polyfill was not applied.

fix

Either import `fetch` explicitly (`import fetch from 'node-fetch-native-with-agent';`) or import the polyfill to make it globally available (`import 'node-fetch-native-with-agent/polyfill';`). Ensure the import statement runs before `fetch` is called.

Upgrade

Version history

1.7.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/loks0n/node-fetch-native ↗

packagehttps://www.npmjs.com/package/node-fetch-native-with-agent ↗