Cannot use import statement outside a module in JavaScript

December 8, 2022

Cannot use import statement outside a module in JavaScript

This guide is part of the “Common JavaScript Errors” series. It’s focused entirely on providing quick and easy solutions for JavaScript-related problems.

The "SyntaxError: Cannot use import statement outside a module" error is thrown when the JavaScript interpreter encounters an import statement outside of a module.

In JavaScript, a module is a code executed in its own scope, separate from the global scope. Import statements can only be used within a module and not in the global scope.

This error can occur in any JavaScript environment, including in Node.js. However, it is more likely to occur in environments that do not support the use of import statements in the global scope, such as older JavaScript engines or browsers.

Fixing it for HTML

To fix the problem for HTML scripts, you need to set the <script> element's type attribute to specify the type of script included in the element.

If the type attribute is set to "module", the browser will know that the script is a JavaScript module and will execute it as such.

This will allow you to use import statements within the script.

Here is an example:

<!-- when loading raw JS -->

<script type="module"></script>

<!-- when loading external files -->

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

Alternatively, you can use a tool like Babel to transpile your code, which will convert the import statements into older syntax that can be used in the global scope. You can then include the transpiled code in your HTML document.

Fixing it for Node.js

To use ES6 module imports in Node.js, you can set the type field in your project's package.json file to specify that your project uses ES6 modules.

Here is an example:

package.json

{
  "name": "my-project",
  "type": "module",
  ...
}

Once you have added the type field to your package.json file, you can use the import statement in your project's JavaScript files without needing to use any special flags.

import myModule from './my-module';

// keep in mind that for local files, you have to append the .js extension to the module, like so:

import myModule from './my-module.js';

// if not you'll get the error: "[ERR_MODULE_NOT_FOUND]: Cannot find module".

This approach has several benefits. First, it does not require you to use any special flags when running the Node.js interpreter, making it more convenient. Second, it allows other tools, such as bundlers and linters, to recognize that your project uses ES6 modules, making it easier to use these tools with your project.

Fixing it for TypeScript

To use the CommonJS module system in a TypeScript project, you will need to enable the allowSyntheticDefaultImports and esModuleInterop compiler options in your TypeScript configuration.

These options allow TypeScript to treat imported values as if they have a default export, even if they do not have one, and to use the import syntax with CommonJS modules.

tsconfig.json

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    ...
  }
}

These options are only supported in TypeScript 3.8 and later.

Another possibility is that you are trying to run your TypeScript files using the node command, rather than using a tool like ts-node to transpile and run them.

In this case, you can use ts-node to transpile and run your files to fix the error.