✋
Update:
This post was originally published on my blog
decodingweb.dev
, where you can read the
latest version
for a 💯 user experience.
~reza
“Error: cannot find module” occurs when you try to load a non-existant
module in Node
– Either via ESM (ECMAScript Modules) or CommonJS module systems.
Import a third-party package you haven't installed yet (with npm or yarn).
Import a local module, but the path is wrong.
Run a node script in the terminal, but the script doesn't exist (or path is wrong).
Use node standard libraries with TypeScript, but you haven't installed the @types/node package.
The module's package.json has a main field pointing to an entry file that doesn't exist.
Before anything, let's review what a module is and how module systems work in a high level (Or jump to the solutions).
The module system: Modules are the building blocks of an application. Node implements ESM and CommonJS (the default one) module systems to let you organize your code as reusable components.
With modules, you can only expose the public interface of your components and keep the internal functionalities private. This is done by using a module.exports (CommonJS modules) or export (ES Modules).
The following code is an example of a module, which has a function to determine whether a number is odd or not:
// math.jsfunctionisOdd(number){returnnumber%2!==0// Make isOdd available to other scripts (and other modules)module.exports=isOdd
If the identifier passed to require() or import() is a reference to a file (it starts with /, ../, ./, etc.) in your filesystem, Node will load it from the respective path. Otherwise, it looks it up in the installed modules - inside the node_modules directory.
If the module isn't found, it raises the "Cannot find module" error.
There are several scenarios this error can happen; Let's explore each.
Third-party packages: If you try to import a third-party module and get this error (and you're sure the spelling is correct), you probably haven't installed the package yet.
Imagine this is the code:
//index.jsconstaxios=require('axios');// Make an HTTP request with Axios
In this case, since utils isn't a reference to a local file, my bundler (Webpack) assumes it's inside a node_modules directory. The build fails as the utils module isn't an installed package.
So what I need to do here is to make it an absolute path by adding ./ to my identifier:
// index.jsconst{getUrl}=require('./utils.js')// Do something here ...
Problem solved.
Sometimes the error occurs because the letter casing is off. File names on Mac and Windows are case-insensitive by default; This means ./Utils and ./utils both work on Mac and Windows (where you develop the app). However, it'll break on a Linux file system where filenames are case-sensitive.
Running a node script: Another scenario reported by developers is when you run a script with the node command. However, the respective file can't be located - probably owing to a typo in the name or path.
So always double-check that the path is correct and the script exists. You can always take advantage of the terminal's autocomplete feature by typing the initial letters and pressing the tab to let it complete the path for you.
node ./scriptName.js
Node and TypeScript: If you're coding in TypeScript and you're importing a built-in Node module like fs, you might get a "Cannot find module 'fs'" error too.
You can fix the issue by installing @types/node:
npm install @types/node --save-dev
If you decide to change the main field to another entry file (e.g., main.js), you must ensure the file exists. Or if you rename or relocate that file in the future, remember to update the package.json too.
Missing entry file in package.json has been reported by several users on Stackoverflow.
Importing a module from the global node_modules or a separate directory: Sometimes you might have to use a globally-installed package in your development environment.
If you try to load a globally-installed module in your project, you might get the "Cannot find module" error.
A workaround to this problem is using the npm link command. If the package is installed globally, all you need to do is run the following command while in your project directory:
npm link package-name
As a result, npm will create a symbolic link from the globally installed package name to the node_modules directory of your project - as if you've installed it with npm install package-name.
If the module you want to use is a local file residing somewhere in your file system other than the global node_modules (e.g., a module you're developing), you'll have to do it in a two-step process:
First step: In the terminal, you need to change the directory to where the module resides and run the npm link (without any parameter). As a result, a symlink is created in the global node_modules that links to your local package.
npm link
This will create a symbolic link from the globally installed package name to the node_modules directory of your project.
Now, you can use the package as if it's an installed third-party package.
If none of the above solutions worked for you, maybe you're dealing with corrupted or incomplete installations. In that case, you can take the following steps:
Delete node_module directory:
rm -rf node_modules
This will make a clean install of all the dependencies listed in your package.json file.
