node-fetch-native

A redistribution of node-fetch v3 (+ more!) for better backward and forward compatibility.

Why this package?

• We can no longer require('node-fetch') with the latest version. This stopped popular libraries from upgrading and dependency conflicts between node-fetch@2 and node-fetch@3.
• With upcoming versions of Node.js, native fetch is being supported. We are prepared for native fetch support using this package yet keep supporting older Node versions.
• With the introduction of native fetch to Node.js via undici there is no easy way to support http proxies!

Features:

✅ Prefer to native globals when available (See Node.js experimental fetch).

✅ Compact build and less install size with zero dependencies ^vs

✅ Support both CommonJS (require) and ESM (import) usage

✅ Use native version if imported without node condition using conditional exports with zero bundle overhead

✅ Polyfill support for Node.js

✅ Compact and simple proxy supporting both Node.js versions without native fetch using HTTP Agent and versions with native fetch using Undici Proxy Agent

Usage

Install node-fetch-native dependency:

# npm
npm i node-fetch-native

# yarn
yarn add node-fetch-native

# pnpm
pnpm i node-fetch-native

You can now either import or require the dependency:

// ESM
import fetch from "node-fetch-native";

// CommonJS
const fetch = require("node-fetch-native");

More named exports:

// ESM
import {
  fetch,
  Blob,
  FormData,
  Headers,
  Request,
  Response,
  AbortController,
} from "node-fetch-native";

// CommonJS
const {
  fetch,
  Blob,
  FormData,
  Headers,
  Request,
  Response,
  AbortController,
} = require("node-fetch-native");

Force using non-native version

Sometimes you want to explicitly use none native (node-fetch) implementation of fetch in case of issues with the native/polyfill version of globalThis.fetch with Node.js or runtime environment.

You have two ways to do this:

• Set FORCE_NODE_FETCH environment variable before starting the application.
• Import from node-fetch-native/node

Polyfill support

Using the polyfill method, we can ensure global fetch is available in the environment and all files. Natives are always preferred.

Note: I don't recommend this if you are authoring a library! Please prefer explicit methods.

// ESM
import "node-fetch-native/polyfill";

// CJS
require("node-fetch-native/polyfill");

// You can now use fetch() without any import!

Proxy Support

Node.js has no built-in support for HTTP Proxies for fetch (see nodejs/undici#1650 and nodejs/node#8381)

This package bundles a compact and simple proxy supported for both Node.js versions without native fetch using HTTP Agent and versions with native fetch using Undici Proxy Agent.

Usage:

import { fetch } from "node-fetch-native"; // or use global fetch
import { createProxy } from "node-fetch-native/proxy";

// Uses HTTPS_PROXY or HTTP_PROXY environment variables
const proxy = createProxy();

// const proxy = createProxy({ url: "http://localhost:8080" });

await fetch("https://google.com", {
  ...proxy,
});

createProxy returns an object with agent for older Node.js versions and dispatcher keys for newer Node.js versions with Undici and native fetch.

If no url option is provided, HTTPS_PROXY or HTTP_PROXY values will be used, and if they also are not set, both agent and dispatcher values will be undefined.

Note

Using export conditions, this utility works in Node.js and for other runtimes, it will simply return a stubbed version as most of the other runtimes now support HTTP proxy out of the box!

Note

Proxy support is under development. Check unjs/node-fetch-native#107 for the roadmap and contributing!

Alias to node-fetch

Using this method, you can ensure all project dependencies and usages of node-fetch can benefit from improved node-fetch-native and won't conflict between node-fetch@2 and node-fetch@3.

npm

Using npm overrides:

// package.json
{
  "overrides": {
    "node-fetch": "npm:node-fetch-native@latest"
  }
}

yarn

Using yarn selective dependency resolutions:

// package.json
{
  "resolutions": {
    "node-fetch": "npm:node-fetch-native@latest"
  }
}

pnpm

Using pnpm.overrides:

// package.json
{
  "pnpm": {
    "overrides": {
      "node-fetch": "npm:node-fetch-native@latest"
    }
  }
}

License

Made with 💛

node-fetch is published under the MIT license