Awesome
node-fetch-native
<!-- [![Codecov][codecov-src]][codecov-href] -->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 betweennode-fetch@2
andnode-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 <sup>vs</sup>
✅ 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 the
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 the 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 solution for both Node.js versions without native fetch using HTTP Agent and versions with native fetch using Undici Proxy Agent.
By default, https_proxy
, http_proxy
, HTTPS_PROXY
, and HTTP_PROXY
environment variables will be checked and used (in order) for the proxy and if not any of them are set, the proxy will be disabled. You can override it using the url
option passed to createFetch
and createProxy
utils.
By default, no_proxy
and NO_PROXY
environment variables will be checked and used for the (comma-separated) list of hosts to ignore the proxy for. You can override it using the noProxy
option passed to createFetch
and createProxy
utils. The entries starting with a dot will be used to check the domain and also any subdomain.
[!NOTE] Using export conditions, this utility adds proxy support for Node.js and for other runtimes, it will simply return native fetch.
[!IMPORTANT] Proxy support is under development. Check unjs/node-fetch-native#107 for the roadmap and contributing!
fetch
with proxy support
You can simply import { fetch }
from node-fetch-native/proxy
with a preconfigured fetch
function that has proxy support.
import { fetch } from "node-fetch-native/proxy";
console.log(await fetch("https://icanhazip.com").then((r) => r.text());
createFetch
utility
You can use the createFetch
utility to instantiate a fetch
instance with custom proxy options.
import { createFetch } from "node-fetch-native/proxy";
const fetch = createFetch({ url: "http://localhost:9080" });
console.log(await fetch("https://icanhazip.com").then((r) => r.text());
createProxy
utility
createProxy
returns an object with agent
and dispatcher
keys that can be passed as fetch options.
import { fetch } from "node-fetch-native";
import { createProxy } from "node-fetch-native/proxy";
const proxy = createProxy();
// const proxy = createProxy({ url: "http://localhost:8080" });
console.log(await fetch("https://icanhazip.com", { ...proxy }).then((r) => r.text());
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 💛 Published under the MIT license.
<!-- Badges -->