Fix Cannot Find Module cross-env Error

Seeing the error "Cannot find module 'cross-env'" can be frustrating. This error stops your Node.js script from running. It happens when npm or your system cannot locate the cross-env package. This article explains why this error occurs and how to fix it. We will use simple steps and examples. You will solve this problem quickly.

What is cross-env?

cross-env is a popular npm package. It lets you set environment variables across different platforms. For example, you can set NODE_ENV on Windows, macOS, or Linux. Without it, scripts that use environment variables may fail. The error "Cannot find module 'cross-env'" means the package is missing from your project. This is a common issue for beginners.

Why Does This Error Happen?

There are three main reasons for this error. First, you may have not installed the package. Second, the package might be installed globally instead of locally. Third, your node_modules folder could be corrupted. Let us explore each cause. We will also provide solutions. If you encounter other module errors, check our guide on Fix Node.js Error: Cannot find module for more help.

How to Fix the Error

Method 1: Install cross-env Locally

The most common fix is to install cross-env as a development dependency. Open your terminal in the project root. Run this command:

npm install --save-dev cross-env

This command adds cross-env to your package.json file. It also downloads the package into the node_modules folder. After installation, try running your script again. The error should be gone.

Example of a script that uses cross-env:

{
  "scripts": {
    "start": "cross-env NODE_ENV=production node app.js"
  }
}

Run it with npm start. The cross-env package sets the environment variable before Node runs.

Method 2: Install cross-env Globally

If you want to use cross-env across multiple projects, install it globally. Use the -g flag:

npm install -g cross-env

Global installation works for system-wide scripts. However, it is better to install locally for project consistency. Global packages can cause version conflicts. Always prefer local installation.

Method 3: Clear npm Cache and Reinstall

Sometimes your node_modules folder gets corrupted. This can happen after a failed install. Delete the folder and reinstall dependencies. Run these commands:

rm -rf node_modules
npm cache clean --force
npm install

On Windows, use rmdir /s node_modules instead. After reinstalling, the cross-env module should be available. This method fixes many module errors. If you still have issues, refer to our detailed guide on Fix Node.js Error: Cannot find module.

Method 4: Check Your package.json

Verify that cross-env is listed in your package.json file. Look under devDependencies or dependencies. If it is missing, add it manually. Then run npm install again. Here is an example:

{
  "devDependencies": {
    "cross-env": "^7.0.3"
  }
}

Make sure the version number is correct. Using a caret (^) allows minor updates. This keeps your project compatible.

Example: Running a Script with cross-env

Let us create a simple Node.js file. We will use cross-env to set an environment variable.

Create a file called app.js with this code:

// app.js
console.log('Environment:', process.env.NODE_ENV);

Add this script to your package.json:

{
  "scripts": {
    "test-env": "cross-env NODE_ENV=development node app.js"
  }
}

Run the script:

npm run test-env

Expected output:

Environment: development

If you get the "Cannot find module" error, the package is not installed. Use the methods above to fix it.

Common Mistakes to Avoid

Beginners often make these mistakes. First, they forget to install the package. Always run npm install --save-dev cross-env before using it. Second, they install it globally but the script expects a local module. Stick to local installation for project scripts. Third, they modify package.json without running npm install. Always run the install command after editing.

Another mistake is using the wrong command. For example, typing cross-env directly in the terminal without npm scripts. The cross-env command works best inside scripts in package.json. Avoid running it standalone.

Conclusion

The "Cannot find module 'cross-env'" error is easy to fix. Install the package locally with npm install --save-dev cross-env. Clear your cache if needed. Check your package.json for the correct entry. Use cross-env inside your npm scripts for cross-platform environment variables. This article provided clear steps and examples. You can now solve this error with confidence. If you face other module errors, our guide on Fix Node.js Error: Cannot find module offers more solutions. Happy coding!