Skip to main content

How to Resolve "SyntaxError: Cannot use import statement outside a module" Error in JavaScript

The SyntaxError: Cannot use import statement outside a module is a common error in modern JavaScript that occurs when you try to use the import or export syntax in a file that the JavaScript runtime is not treating as an ES Module. This error can happen in both the browser and in Node.js, and while the cause is the same, the solution is specific to each environment.

This guide will explain what a JavaScript module is and teach you how to correctly configure both your browser <script> tags and your Node.js package.json to enable ES Module support and fix this error.

Understanding the Error: Scripts vs. Modules​

By default, JavaScript runtimes treat .js files as simple "scripts". A script is a file that is executed from top to bottom in the global scope. In this "classic" script mode, the keywords import and export are not recognized and will throw a SyntaxError.

An ES Module is a file that has its own, self-contained scope. It can explicitly export variables, functions, or classes, and it can import them from other modules. To use this feature, you must explicitly tell the runtime environment (the browser or Node.js) to treat your file as a module.

The error "Cannot use import statement outside a module" is the runtime telling you, "You used the import keyword, but you didn't tell me this was a module."

Solution 1: in the Browser​

In a browser environment, you must add the type="module" attribute to your <script> tag.

In the following example of code (with problems), without type="module", the browser loads index.js as a classic script.

<!DOCTYPE html>
<html>
  <body>
    <!-- ⛔️ BAD: This will cause the error if index.js uses 'import'. -->
    <script src="index.js"></script>
  </body>
</html>

index.js:

// ⛔️ Uncaught SyntaxError: Cannot use import statement outside a module
import { myUtility } from './utils.js';

The Solution is to add type="module": this attribute tells the browser to treat the file and any files it imports as ES Modules.

<!DOCTYPE html>
<html>
  <body>
    <!-- ✅ GOOD: The 'type="module"' attribute enables ES Module syntax. -->
    <script type="module" src="index.js"></script>
  </body>
</html>

Now, index.js can correctly use the import and export syntax.

Solution 2: in Node.js​

In a Node.js environment, you must tell Node.js to treat your .js files as ES Modules by setting the type property in your project's package.json file.

You have a project with two files, and you try to run it with node index.js.

utils.js
export function greet() {
  console.log('Hello!');
}
index.js
// ⛔️ (node:...) SyntaxError: Cannot use import statement outside a module
import { greet } from './utils.js';
greet();

The Solution is to add "type": "module" to package.json: this setting tells Node.js that all .js files in your project should be treated as ES Modules.

{
  "name": "my-project",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

With this change, node index.js will now work correctly.

Alternative (Legacy): Using require If you cannot use ES Modules, you must use the older CommonJS syntax, which uses require() for imports and module.exports for exports. If you use this syntax, you must remove "type": "module" from your package.json.

// Using CommonJS syntax
const { greet } = require('./utils.js');

A Note on TypeScript​

If you are using TypeScript, this error usually means you are trying to run your TypeScript (.ts) files directly with node instead of compiling them first.

  • The Fix: Compile your project with tsc. This will convert your TypeScript import/export syntax into the JavaScript format specified in your tsconfig.json (usually CommonJS require). Then, run the compiled .js files from your dist or build folder.
  • Development: Use a tool like ts-node which handles the compilation and execution in one step.

Common Pitfalls and Best Practices​

  • File Extensions are Mandatory in ES Modules: When using import in Node.js (with "type": "module"), you must include the full file extension in your import paths. 
    // ⛔️ BAD: This will fail in Node.js ES Modules.
    import { greet } from './utils';

    // ✅ GOOD: Always include the .js extension.
    import { greet } from './utils.js';
  • default vs. Named Exports: Be careful not to mix up your export and import styles. 
    // Named export:   export const myVar = ...
    // Named import:   import { myVar } from './file.js';

    // Default export: export default myVar;
    // Default import: import myVar from './file.js';

Conclusion​

The SyntaxError: Cannot use import statement outside a module error is a simple configuration issue that tells you the JavaScript runtime is treating your file as a classic script instead of a modern ES Module.

To fix it:

  • In the Browser: Add type="module" to your <script> tag.
  • In Node.js: Add "type": "module" to your package.json file.
  • In TypeScript: Compile your code first with tsc, or use a runner like ts-node.

By correctly configuring your environment, you can take full advantage of the clean and powerful ES Module system.

Table of Contents