"Uncaught SyntaxError: Cannot use import statement outside a module" when importing ECMAScript 6

Matthew C.

—March 15, 2024

The Problem

You are trying to import an item such as a function from one JavaScript file into another JavaScript file. For example:

import { toKebabCase } from '/yourFile.js';

After importing this function, you get the following error:

"Uncaught SyntaxError: Cannot use import statement outside a module" when importing ECMAScript 6

This error occurs because the JavaScript file uses an import statement in a file that’s not an ES module. ECMAScript is the language specification that JavaScript conforms to. The ECMAScript 6 (ES6), also known as ES2015, specification revision added ES modules to JavaScript. Modules were added to allow programmers to split JavaScript programs into separate modules that allow for easy sharing of items such as variables and functions and better organization of code.

A module is a JavaScript file that exports one or more values using the export statement. For example:

export const startVal = 2;

export function myFunction() {
  //
}

The value can then be imported into another module using the import statement. For example:

import { startVal, myFunction } from './yourFile.js';

ES modules can make items such as variables, available to other modules that are outside of their scope using an export statement. Before modules, you would have to move a value to a higher scope, such as the global scope, if you wanted to make it available outside of its scope. Adding values to the global scope can lead to all sorts of issues and makes code hard to maintain. Modules allow for better code organization, sharing of values is explicit. Most modern browsers support ES modules.

Node.js has two module systems: CommonJS modules and ES modules. ES modules were added to Node.js in version 15.3.0.

The Solution

If your JavaScript file was added to your project using a <script> tag, add a type attribute with a value of “module” to your script tag:

<script type="module" src="./yourFile.js"></script>

Node.js, version 15.3.0 and above support ES modules. Older versions use CommonJS only unless you use a library such as esm that allow for ES modules in Node.js version 6 and above. In Node.js versions that support ES modules, you need to set the value of the "type" field to “module” in the package.json file:

{
  "type": "module"
}

Alternatively, you can use the .mjs file extension to indicate to Node.js that the file is an ES module.