{"id":11420,"library":"node-fetch-native","title":"Node.js `fetch` Compatibility Layer","description":"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.","status":"active","version":"1.6.7","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/node-fetch-native","tags":["javascript","typescript"],"install":[{"cmd":"npm install node-fetch-native","lang":"bash","label":"npm"},{"cmd":"yarn add node-fetch-native","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-fetch-native","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ESM projects. This is the primary way to import the default fetch implementation.","wrong":"const fetch = require('node-fetch-native');","symbol":"fetch","correct":"import fetch from 'node-fetch-native';"},{"note":"For CommonJS projects. This package ensures backward compatibility for 'require' despite underlying ESM changes in node-fetch v3.","wrong":"import fetch from 'node-fetch-native';","symbol":"fetch (CommonJS)","correct":"const fetch = require('node-fetch-native');"},{"note":"Both ESM and CommonJS support named exports for Fetch API primitives.","wrong":"const { Headers, Request, Response } = require('node-fetch-native');","symbol":"Named exports (Headers, Request, Response)","correct":"import { fetch, Headers, Request, Response } from 'node-fetch-native';"},{"note":"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`.","wrong":"import { fetch } from 'node-fetch-native/node';","symbol":"Force non-native fetch","correct":"import fetch from 'node-fetch-native/node';"},{"note":"Imports the polyfill to make `fetch` available globally. Not recommended for library authors, prefer explicit imports.","wrong":"require('node-fetch-native/polyfill');","symbol":"Polyfill global fetch","correct":"import 'node-fetch-native/polyfill';"}],"quickstart":{"code":"import fetch, { Headers, Request } from 'node-fetch-native';\nimport 'node-fetch-native/polyfill'; // Optional: ensures global fetch is available\n\nasync function runExample() {\n  console.log(\"--- Basic Fetch Example ---\");\n  try {\n    const response = await fetch(\"https://api.github.com/zen\");\n    const text = await response.text();\n    console.log(`GitHub Zen says: \"${text}\"`);\n  } catch (error) {\n    console.error(\"Basic fetch failed:\", error);\n  }\n\n  console.log(\"\\n--- Fetch with Named Exports Example ---\");\n  try {\n    const headers = new Headers({ \"Content-Type\": \"application/json\" });\n    const request = new Request(\"https://jsonplaceholder.typicode.com/posts\", {\n      method: \"POST\",\n      headers: headers,\n      body: JSON.stringify({ title: \"foo\", body: \"bar\", userId: 1 }),\n    });\n    const response = await fetch(request);\n    const data = await response.json();\n    console.log(\"POST request response:\", data);\n  } catch (error) {\n    console.error(\"Named exports fetch failed:\", error);\n  n}\n\n  // Example of using a proxy (requires setting environment variables like HTTP_PROXY)\n  if (process.env.HTTP_PROXY || process.env.HTTPS_PROXY) {\n    console.log(\"\\n--- Proxy-aware Fetch (if env vars are set) ---\");\n    try {\n      const response = await fetch(\"http://example.com\");\n      console.log(`Fetched http://example.com via proxy (status: ${response.status})`);\n    } catch (error) {\n      console.error(\"Proxy fetch failed:\", error);\n    }\n  } else {\n    console.log(\"\\n--- Proxy-aware Fetch: Set HTTP_PROXY or HTTPS_PROXY environment variable to test. ---\");\n    console.log(\"Example: export HTTP_PROXY=http://localhost:8080\");\n  }\n}\n\nrunExample();","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your build setup correctly handles ESM imports if you are using 'import'. For CommonJS, continue using 'require' with `node-fetch-native`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"To suppress this warning, set the environment variable `DISABLE_NODE_FETCH_NATIVE_WARN=1` before running your application.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.5.0"},{"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'`).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` an ESM-only package like `node-fetch` v3, which this package wraps, in a strict CommonJS environment without proper resolution.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... node-fetch-native ... not supported."},{"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.","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.","error":"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."},{"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`.","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.","error":"Fetch requests are not routing through my HTTP proxy."}],"ecosystem":"npm"}