How to fix SyntaxError: Cannot use import statement outside a module


Consider supporting my work if you though that was helpful


When developing apps of scripts using Node JS you may encounter this error:

SyntaxError: Cannot use import statement outside a module

There are several ways to fix this, in this post we go over the various different ways there are to fix this error so you can chose the best one for your use case.

Why does this error occur?

Node is a great platform to develop your apps on, however, as any ecosystem is comes with some shortcomings. One such drawback to Javascript is that it has become a fragmented ecosystem.

Node JS was released in 2009, way before modern JavaScript became a thing. In fact, it’s Node JS (among others) that sparked the interest of thousands of developers to adopt it as their main development tool. Historically there has been a lack of standardisation for common programming concepts such as organising your code in modules, importing and exporting them across your code base.

One of the earlier projects that unified the way we import and export modules, packages or functions was CommonJS. Node adopted this convention from the beginning and it’s still the default convention for all Node versions.

Since Node version 13, however, Node.js has also broad support for a more modern API for managing modules, which es known as ES Modules.

Node JS still uses CommonJS as it’s default version of JavaScript, so when you get a SyntaxError: Cannot use import statement outside a module error, this is because you’re trying to write code using the ES Modules syntax (modern JavaScript) in a project that Node believes to be CommonJS.

While ES Modules give you access to a more modern and readable way of managing your imports using the import / export API instead of CommonJS’ require, you do need to tell Node.js you intend to use this API.

The fix for 99% of projects

Simply tell Node JS your project should use ES Modules instead of CommonJS. This can be done by adding 1 simple line of code to your package.json file:

  "type": "module",

By simply adding "type": "module" to your package.json file you’re telling Node to use ES Modules as the JS version for this project, and your issue should be resolved.

The fix for Browser based projects

If you’re developing a browser based app, you can also run into the same issue. The fix is equally simple there.

If you import a JS script similar to this, for example:

<script src="main.js"></script>

All you need to add is type="module" into the script tag like this:

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

The fix for Typescript projects

To fix the SyntaxError: Cannot use import statement outside a module error you need to change 2 files:

  • package.json
  • tsconfig.json

Add "type": "module" to your package.json just like the fix for any Node.js project

  "type": "module",

Make sure your tsconfig.json file has these 2 properties set to these values:

  "target": "esnext",
  "module": "commonjs",

Leave a Reply

Your email address will not be published. Required fields are marked *