Skip to main content

How to Resolve "Node.js Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension"

The warning (node:...) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension is a common message in Node.js. It occurs when you try to run a file that uses the modern ES Module (import/export) syntax, but your Node.js project is not configured to interpret the file as an ES module.

This guide will explain the fundamental difference between Node.js's module systems and show you the two standard ways to fix this warning.

The Core Problem: CommonJS vs. ES Modules in Node.js​

Node.js has historically used a module system called CommonJS, which uses the require() and module.exports syntax. This is the default system.

However, the official standard for modules in JavaScript is now ES Modules, which uses the import and export syntax.

The warning message is Node.js telling you: "You've written your code using import/export, but I'm currently in CommonJS mode, which doesn't understand this syntax. You need to tell me to switch to ES Module mode."

Example of problem: index.js:

// This is ES Module syntax.
import moment from 'moment';

console.log(moment().format());

When you run this file in a default Node.js project, you will get the warning.

Error Output:

(node:...) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
...
SyntaxError: Cannot use import statement outside a module

This is the most common and modern approach. By adding a single property to your project's package.json file, you tell Node.js to treat all .js files in that project as ES Modules.

Solution:

  1. If you don't have one, create a package.json file by running npm init -y in your project's root directory.
  2. Open your package.json file and add the "type": "module" property.

package.json:

{
  "name": "my-node-app",
  "version": "1.0.0",
  "type": "module" 
}
note

Now, when you run node index.js, the file will be correctly interpreted as an ES Module, and the warning will be gone.

Solution 2: Use the .mjs File Extension​

If you don't want to change your entire project to ES Modules, you can signal to Node.js that a specific file is an ES module by changing its extension from .js to .mjs.

Solution: simply rename your file.

  • index.js -> index.mjs
// This file is now named `index.mjs`
import moment from 'moment';

console.log(moment().format());
note

Node.js will now automatically interpret this file as an ES module, even without the "type": "module" setting in package.json. This is a great option for gradually introducing ES modules into an existing CommonJS project.

A Note on require vs. import​

Once you configure your project to use ES Modules (either with "type": "module" or .mjs files), you must use the import/export syntax consistently. You can no longer use the CommonJS require() function to import modules.

  • ES Modules: import moment from 'moment';
  • CommonJS: const moment = require('moment');
note

Mixing them in the same file in an unsupported way will lead to errors.

Conclusion​

The "To load an ES module, set "type": "module"..." warning is a clear indicator that you are using modern import/export syntax in a project that Node.js is treating as a traditional CommonJS project.

To solve it, you have two excellent options:

  1. Set "type": "module" in your package.json: This is the recommended best practice for modern Node.js projects, as it makes ES Modules the default for all .js files.
  2. Rename your file with a .mjs extension: This is a great way to mark a single file as an ES Module without changing your whole project's configuration.

By explicitly telling Node.js which module system to use, you will resolve the warning and be able to use the modern, powerful ES Module syntax.

Table of Contents