How to fix: cannot use import statement outside a module

JavaScript's import statement, which loads modules asynchronously, sometimes triggers an error when the runtime environment doesn't recognize the context as a module. This guide covers how to resolve the "Cannot use import statement outside a module" error.

Understanding the import statement in JavaScript

The import statement in JavaScript is used to load modules and their exported components into other scripts or modules. This ES6 feature enables code splitting, reduces redundancy, and enhances code organization. However, using import outside the expected module context can lead to execution errors.

import { functionName } from './module.js';

Common causes of the import error

Script context is not a module

If a script containing the import statement isn't running as a module, JavaScript engines throw an error.

Incorrect MIME type for JavaScript files

When serving js modules over the network, the server must use the correct MIME type (text/javascript) for them to be recognized as modules.

Browsers do not support module features

Older browsers or certain environments may not support the ES6 module system, resulting in the import error.

How to resolve the import error

Set the type attribute to module

For HTML <script> tags that contain or reference scripts with import statements, set the type attribute to module.

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

Ensure the server sends the correct MIME type

Configure your server to serve .js files with the text/javascript MIME type. For example, in Apache, you would add the following to your .htaccess file:

AddType text/javascript .js

Use module bundlers or transpilers

Employ tools like Webpack, Rollup, or Babel to bundle your modules and transpile code into a format that browsers without ES6 support can execute.

// Using Babel CLI to transpile modules
babel src --out-dir lib

Update your JavaScript environment

Ensure your JavaScript runtime, whether it's a browser or server-side environment like Node.js, is updated to a version that supports ES6 modules.

Configure Node.js for ES module support

If you're using Node.js, you may need to do the following:

• Rename your files with .mjs extension to explicitly mark them as modules.
• Use the "type": "module" in your package.json to treat .js files as modules.
• Ensure you are using a version of Node.js that supports ES modules.

// In package.json
{
  "type": "module"
}

Refactor to use CommonJS syntax

If modules are not a requirement, refactor the code to use CommonJS syntax, which is supported in more environments without configuration.

const { functionName } = require('./module');

Testing module compatibility

After making changes to resolve the import error, test your application thoroughly to ensure that all modules are loading correctly and that no new issues have arisen.

import { testName } from './module.js';
console.assert(typeof testName === 'function', 'Module did not load correctly');

Conclusion

The "Cannot use import statement outside a module" error is a signal to check your script's context, server configuration, and runtime environment for module support. With proper configuration and tooling, you can leverage the power of ES6 modules to create scalable and maintainable JavaScript applications.