Node.js `fetch` Compatibility Layer

Common errors

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

  cause 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.

  cause 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.

  cause 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`.

Warnings

• breaking The 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`.
• gotcha When 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.
• gotcha HTTP/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.
• gotcha The 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'`).

Install

• npm install node-fetch-native npm
• yarn add node-fetch-native yarn
• pnpm add node-fetch-native pnpm

Imports

• fetch
  wrong:

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

  correct:

  import fetch from 'node-fetch-native';

  For ESM projects. This is the primary way to import the default fetch implementation.
• fetch (CommonJS)
  wrong:

  import fetch from 'node-fetch-native';

  correct:

  const fetch = require('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)
  wrong:

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

  correct:

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

  Both ESM and CommonJS support named exports for Fetch API primitives.
• Force non-native fetch
  wrong:

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

  correct:

  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
  wrong:

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

  correct:

  import 'node-fetch-native/polyfill';

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

Quickstart

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();