Fixing ERR_REQUIRE_ESM Error with node-fetch

Problem Statement

When trying to import node-fetch version 3.0.0 or later using CommonJS require() syntax:

const fetch = require('node-fetch')

You may encounter the following error:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported.

This occurs because starting with version 3.0.0, node-fetch transitioned to being an ES Module (ESM)-only package, which cannot be imported using CommonJS require() statements.

Solutions

Option 1: Downgrade to node-fetch v2 (Recommended for CommonJS projects)

The simplest solution for existing CommonJS projects is to downgrade to version 2.x:

npm uninstall node-fetch
npm install node-fetch@2

This version maintains CommonJS compatibility and continues to receive critical bug fixes.

Option 2: Use Dynamic Import (Node.js 12+)

For projects that need the latest version but must remain in CommonJS, use dynamic imports:

const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));

You can also create a wrapper module:

// fetch.js
exports.fetch = async function (url, init) {
    const {default: fetch} = await import("node-fetch");
    return await fetch(url, init);
};

Then import it in your main file:

const {fetch} = require("./fetch");

Option 3: Use Node.js 18+ Built-in Fetch (Modern Alternative)

INFO

Node.js 18.0.0+ includes a built-in fetch API (experimental but enabled by default)

If you're using Node.js 18 or later, you can use the native fetch implementation:

const res = await fetch('https://api.example.com/data');
if (res.ok) {
  const data = await res.json();
  console.log(data);
}

This global fetch API comes with support for FormData, Headers, Request, and Response objects.

Option 4: Alternative Packages

Consider these alternatives that maintain CommonJS compatibility:

cross-fetch (supports both CommonJS and ESM):

npm install cross-fetch

const fetch = require('cross-fetch');

node-fetch-commonjs (CommonJS wrapper):

npm install node-fetch-commonjs

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

Understanding the Change

Node.js supports two module systems:

• CommonJS: Uses require() and module.exports
• ES Modules (ESM): Uses import and export statements

Starting with version 3.0.0, node-fetch became an ESM-only package to leverage modern JavaScript features and improve tree-shaking capabilities. This change aligns with the broader JavaScript ecosystem's shift toward ES modules.

Migration Considerations

When choosing a solution, consider:

1. Project requirements: Does your project need specific features from v3?
2. Node.js version: Are you using Node.js 18+ with built-in fetch?
3. Codebase structure: Is your project ready to transition to ES modules?
4. Dependencies: Do other packages in your project have ESM compatibility requirements?

TIP

For most existing CommonJS projects, downgrading to node-fetch@2 or using cross-fetch provides the simplest migration path without disrupting your current codebase structure.

Best Practices

1. Check Node.js version compatibility before implementing any solution
2. Consider migrating to ES Modules for long-term maintainability
3. Test thoroughly after making changes to ensure fetch functionality works as expected
4. Update documentation to reflect any changes in import patterns

By understanding the root cause of the ERR_REQUIRE_ESM error and selecting the appropriate solution for your project, you can continue using fetch functionality in Node.js without disruption.