Registry / http-networking / node-fetch-native

node-fetch-native

library1.6.7jsnpmunverified

node-fetch-native is a lightweight package designed to provide a consistent `fetch` API across various JavaScript runtimes, primarily targeting Node.js. It intelligently prefers Node.js's experimental native `fetch` (backed by `undici`) when available, falls back to an internal `node-fetch v3` implementation for older Node.js versions, and offers comprehensive HTTP/HTTPS proxy support, which is not natively available in Node.js's built-in `fetch` implementation. Currently stable at version `1.6.7`, the package maintains a steady release cadence, often addressing dependency updates and minor bug fixes. A key differentiator is its ability to bridge the `CommonJS` (`require`) and `ESM` (`import`) divide for `fetch`, resolving common migration issues encountered with `node-fetch` v3. It also provides a polyfill mechanism to ensure global `fetch` availability.

http-networking

npm install node-fetch-native

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-FETCH-NATIVE

node-fetch-native

http-networkingjavascriptv1.6.7

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';

✗ const fetch = require('node-fetch-native');

For ESM projects. This is the primary way to import the default fetch implementation.

fetch (CommonJS)

✓ const fetch = require('node-fetch-native');

✗ import fetch from 'node-fetch-native';

For CommonJS projects. This package ensures backward compatibility for 'require' despite underlying ESM changes in node-fetch v3.

Named exports (Headers, Request, Response)

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

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

Both ESM and CommonJS support named exports for Fetch API primitives.

Force non-native fetch

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

✗ import { fetch } from 'node-fetch-native/node';

Use this subpath import to explicitly force the bundled node-fetch implementation, bypassing Node.js's native fetch. Can also be achieved by setting `FORCE_NODE_FETCH=1`.

Polyfill global fetch

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

✗ require('node-fetch-native/polyfill');

Imports the polyfill to make `fetch` available globally. Not recommended for library authors, prefer explicit imports.

Demonstrates basic `fetch` usage, fetching with named `Headers` and `Request` objects, and shows how `node-fetch-native` inherently supports HTTP/HTTPS proxies when `HTTP_PROXY` or `HTTPS_PROXY` environment variables are configured. It highlights both default and named imports.

import fetch, { Headers, Request } from 'node-fetch-native'; import 'node-fetch-native/polyfill'; // Optional: ensures global fetch is available async function runExample() { console.log("--- Basic Fetch Example ---"); try { const response = await fetch("https://api.github.com/zen"); const text = await response.text(); console.log(`GitHub Zen says: "${text}"`); } catch (error) { console.error("Basic fetch failed:", error); } console.log("\n--- Fetch with Named Exports Example ---"); try { const headers = new Headers({ "Content-Type": "application/json" }); const request = new Request("https://jsonplaceholder.typicode.com/posts", { method: "POST", headers: headers, body: JSON.stringify({ title: "foo", body: "bar", userId: 1 }), }); const response = await fetch(request); const data = await response.json(); console.log("POST request response:", data); } catch (error) { console.error("Named exports fetch failed:", error); n} // Example of using a proxy (requires setting environment variables like HTTP_PROXY) if (process.env.HTTP_PROXY || process.env.HTTPS_PROXY) { console.log("\n--- Proxy-aware Fetch (if env vars are set) ---"); try { const response = await fetch("http://example.com"); console.log(`Fetched http://example.com via proxy (status: ${response.status})`); } catch (error) { console.error("Proxy fetch failed:", error); } } else { console.log("\n--- Proxy-aware Fetch: Set HTTP_PROXY or HTTPS_PROXY environment variable to test. ---"); console.log("Example: export HTTP_PROXY=http://localhost:8080"); } } runExample();

Debug

Known issues

breakingThe underlying `node-fetch` package moved to ESM-only in v3, breaking `require()` usage for many projects. While `node-fetch-native` provides compatibility for both CommonJS and ESM, users migrating from older `node-fetch` versions should be aware of this ecosystem shift.

fix

Ensure your build setup correctly handles ESM imports if you are using 'import'. For CommonJS, continue using 'require' with `node-fetch-native`.

affects: >=1.0.0

gotchaWhen importing from `node-fetch-native/node` to explicitly use the non-native implementation, a warning may be logged if the current runtime is not Node.js.

fix

To suppress this warning, set the environment variable `DISABLE_NODE_FETCH_NATIVE_WARN=1` before running your application.

affects: >=1.0.0

gotchaHTTP/HTTPS proxy support relies on standard environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). If these are not correctly configured, proxy functionality will not activate.

fix

Set `HTTP_PROXY` and/or `HTTPS_PROXY` environment variables to your proxy server address (e.g., `export HTTP_PROXY=http://localhost:8080`). Use `NO_PROXY` for exclusions.

affects: >=1.5.0

gotchaThe package attempts to prefer Node.js's native `fetch` when available. If you experience unexpected behavior or need specific `node-fetch` features not present in the native implementation, you might need to force the non-native version.

fix

Set the environment variable `FORCE_NODE_FETCH=1` or import `fetch` from `node-fetch-native/node` (e.g., `import fetch from 'node-fetch-native/node'`).

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module ... node-fetch-native ... not supported.

Attempting to `require()` an ESM-only package like `node-fetch` v3, which this package wraps, in a strict CommonJS environment without proper resolution.

fix

Use `node-fetch-native` with `require('node-fetch-native')` as it provides a CommonJS-compatible export. If explicitly trying to load `node-fetch` directly, ensure your project is configured for ESM or use an older `node-fetch` v2.

Warning: `node-fetch-native/node` is loaded in a non-Node.js environment. Consider importing from `node-fetch-native` directly if this is not intended.

This warning occurs when you explicitly import the Node.js-specific `node-fetch-native/node` subpath in a runtime that is detected as non-Node.js.

fix

If you are running in a Node.js environment and want to disable this warning, set the `DISABLE_NODE_FETCH_NATIVE_WARN=1` environment variable. If you are not in Node.js, reconsider if you need the Node.js-specific implementation.

Fetch requests are not routing through my HTTP proxy.

HTTP proxy support for `fetch` in Node.js (including native `fetch`) requires explicit configuration, typically via environment variables, as it's not a built-in feature.

fix

Ensure `HTTP_PROXY` and `HTTPS_PROXY` environment variables are correctly set before starting your application. For example, `export HTTP_PROXY=http://your.proxy.com:port`.

Upgrade

Version history

1.6.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

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

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