If you’ve ever seen the error message:
SyntaxError: Cannot use import statement outside a module
you’re not alone. It’s one of the most common JavaScript errors developers encounter, especially when working with modern ES modules (ESM) in Node.js or the browser.
At first glance, the error sounds cryptic — but the cause is actually simple once you understand how JavaScript modules work. In this guide, we’ll break down what this error means, why it happens, and how to fix it properly in different environments.
What This Error Really Means
This error appears when you use the import statement in a JavaScript file that the runtime (Node.js or browser) doesn’t recognize as an ES module.
For example, you might have code like this:
import express from ‘express’;
If you run that in Node.js using a .js file without telling Node it’s a module, you’ll get:
SyntaxError: Cannot use import statement outside a module
This happens because import and export are part of the ES module system (ESM), while Node.js and browsers also support another system called CommonJS (CJS) that uses require() and module.exports.
In short:
- ES Modules use import and export.
- CommonJS uses require() and module.exports.
When you mix the two or run ESM syntax in a file Node thinks is CommonJS, the runtime doesn’t know how to interpret it — hence the error.
Why It Happens
There are several common situations that trigger this error:
1. Running ES Modules in Node Without Proper Configuration
By default, older versions of Node.js treat .js files as CommonJS modules.
If you use import in such a file without telling Node it’s an ES module, you’ll get this error.
2. Missing or Incorrect “type”: “module” in package.json
Node.js relies on the “type” field in your package.json file to determine whether .js files should be treated as ES modules or CommonJS.
If it’s missing or set incorrectly, Node assumes CommonJS mode.
3. Using Import in Browser Without Module Script
In browsers, if you write an import statement in a script that isn’t defined as type=”module”, the browser won’t know how to process it.
4. Mixing CommonJS and ES Modules
Sometimes developers import ES modules inside CommonJS files (or vice versa). This hybrid approach can lead to compatibility issues and trigger this syntax error.
How to Fix “Cannot Use Import Statement Outside a Module”
Let’s look at several ways to fix this issue depending on your setup.
1. Tell Node.js to Treat Your Code as an ES Module
If you’re using Node.js 12+, you can enable ES module support by adding this to your package.json:
{
“type”: “module”
}
Now, Node will interpret all .js files in your project as ES modules.
You can safely use syntax like:
import express from ‘express’;
and it will run without errors.
If you want to mix both module types, you can:
- Use .mjs for ES modules
- Use .cjs for CommonJS modules
Example:
index.mjs
server.cjs
This way, Node knows which syntax to expect in each file.
2. Use CommonJS Syntax Instead
If your project isn’t set up for ES modules and you prefer to keep things simple, you can switch to CommonJS syntax:
const express = require(‘express’);
This will work in all Node environments without additional configuration.
3. Configure Babel or a Bundler
If you’re working with frontend code that uses modern JavaScript (ES6+) and runs in the browser, tools like Babel, Vite, Webpack, or Rollup can transpile your ES module code into browser-compatible syntax.
For example, if your code uses imports:
import { calculateTotal } from ‘./utils.js’;
Your build tool will compile it into something the browser understands.
This is especially useful if you’re targeting older browsers that don’t fully support ES modules.
4. Use <script type=”module”> in HTML
If you’re running code directly in the browser, you need to tell the browser that your script is a module:
<script type=”module” src=”main.js”></script>
This way, the browser knows to interpret your JavaScript file as an ES module and allows the use of import and export.
Without type=”module”, you’ll get the same “Cannot use import statement outside a module” error.
5. Check File Extensions
Node.js treats .mjs files as ES modules by default.
If you don’t want to change your package.json, simply rename your file:
index.js → index.mjs
Then run:
node index.mjs
Node will recognize it as a module and process your imports correctly.
6. Be Careful When Mixing Module Systems
If you’re working with a library or package that uses a different module system than your project, make sure you’re importing it correctly.
For example:
- To use CommonJS inside ESM:
import pkg from ‘package-name’;
const { something } = pkg;
- To use ESM inside CommonJS:
const module = await import(‘./module.mjs’);
But note that this approach should be used sparingly — it’s better to stick with one module system for consistency.
Example Fix: From Error to Working Code
Let’s walk through a common example.
Incorrect setup:
// app.js
import express from ‘express’;
const app = express();
app.listen(3000);
Running:
node app.js
You’ll get:
SyntaxError: Cannot use import statement outside a module
Fixed setup:
Add “type”: “module” to package.json:
{
“type”: “module”
}
Run again:
node app.js
Now it works — no error, and your server runs correctly.
Why Understanding This Matters
While it’s tempting to just switch syntax until the error disappears, understanding why it happens makes you a stronger developer.
JavaScript’s module system has evolved over time, and the coexistence of CommonJS and ES modules is one of the trickiest aspects for beginners. Knowing how each works helps you:
- Configure your environment correctly.
- Avoid unpredictable behavior.
- Write cleaner, more maintainable code.
In modern development, ES modules are the standard moving forward. Frameworks like React, Next.js, and Vue have already embraced them, and Node.js provides full support.
Best Practices to Avoid the Error
- Be consistent — stick to one module system across your project.
- Set “type”: “module” early if you plan to use import/export.
- Use .mjs for clarity when mixing older and newer modules.
- Add bundling tools if your project targets older browsers.
- Avoid mixing ESM and CJS syntax unless necessary.
Final Thoughts
The “SyntaxError: Cannot use import statement outside a module” message is not a bug in your code — it’s a signal that your JavaScript environment and module syntax are misaligned.
By understanding how Node.js and browsers interpret modules, and by configuring your project correctly, you can eliminate this issue permanently.
Whether you’re writing backend code in Node.js or frontend code in the browser, the key is to clearly define your module type — once that’s in place, your imports will work seamlessly.