{"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,"search_vec":"'1.6.7':77 'abil':98 'across':20 'address':86 'also':121 'api':19 'avail':39,64,130 'back':35,41 'bridg':100 'bug':91 'built':69 'built-in':68 'cadenc':84 'common':111 'commonj':102 'compat':3 'comprehens':56 'consist':17 'current':73 'depend':87 'design':13 'differenti':95 'divid':107 'encount':114 'ensur':127 'esm':105 'experiment':32 'fall':40 'fetch':2,7,18,34,47,71,109,118,129 'fix':92 'global':128 'http/https':57 'implement':49,72 'import':106 'intellig':28 'intern':44 'issu':113 'javascript':22,131 'key':94 'layer':4 'lightweight':11 'maintain':80 'mechan':125 'migrat':112 'minor':90 'nativ':8,33,63 'node':6,46,117 'node-fetch':45,116 'node-fetch-n':5 'node.js':1,26,30,52,66 'offer':55 'often':85 'older':51 'packag':12,79 'polyfil':124 'prefer':29 'primarili':24 'provid':15,122 'proxi':58 'releas':83 'requir':103 'resolv':110 'runtim':23 'stabl':74 'steadi':82 'support':59 'target':25 'typescript':132 'undici':37 'updat':88 'v3':48,119 'various':21 'version':53,76","created_at":"2026-04-19T13:37:53.534985+00:00","updated_at":"2026-04-19T13:37:53.534985+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/unjs/node-fetch-native","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-fetch-native","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}