“Cannot Use Import Statement Outside a Module”: Explained & Fixed – wiki基地

作者： /

“Cannot Use Import Statement Outside a Module”: Explained & Fixed

The error message “Cannot use import statement outside a module” is a common hurdle for JavaScript developers, especially when transitioning between different module systems or setting up new projects. This article will thoroughly explain why this error occurs and provide clear, actionable steps to fix it.

Understanding the Error

At its core, this error indicates a mismatch between how you are writing your JavaScript code (using import and export statements) and how the JavaScript runtime (browser or Node.js) is interpreting it.

JavaScript Module Systems:

Historically, JavaScript lacked a native module system. Developers relied on various patterns like the Module Pattern, CommonJS (used predominantly in Node.js with require() and module.exports), or AMD (Asynchronous Module Definition).

With the advent of ES2015 (ES6), ECMAScript Modules (ESM) were introduced as the official, standardized module system for JavaScript. ESM uses the import and export keywords, providing a cleaner and more efficient way to organize and reuse code.

The “Cannot use import statement outside a module” error arises because import and export syntax are exclusive to ESM. If your JavaScript environment is configured to treat your file as a “script” rather than a “module,” it won’t understand these keywords, leading to the error.

Common Causes of the Error

  1. Missing or Incorrect type="module" in HTML: When using import statements in browser-side JavaScript, the <script> tag loading your main JavaScript file must explicitly declare type="module". Without this, the browser defaults to interpreting the script as a classic, non-modular script.

    “`html



    “`

  2. Node.js Project Configuration: In Node.js, the default module system is CommonJS. If you want to use ESM (import/export) in your Node.js project, you need to explicitly tell Node.js to treat your files as modules.

  3. Mixing CommonJS and ESM Syntax: Attempting to use import in a file that is otherwise treated as a CommonJS module (or vice-versa) will lead to this error. This often happens in older Node.js projects or when integrating third-party libraries that use different module systems.

  4. Incorrect File Extensions: While less common now, some bundlers or environments might rely on file extensions (.mjs for ESM, .cjs for CommonJS) to infer the module type.

How to Fix the Error

The solution depends on your environment (browser or Node.js) and your project’s setup.

Fix for Browser Environments

If you’re developing for the browser and seeing this error, the most common fix is to properly declare your script as a module in your HTML:

“`html






My ESM App

Hello, ESM!




“`

Important Considerations for Browser ESM:

  • Deferred Execution: Scripts with type="module" are deferred by default, similar to defer attribute on regular scripts. They execute after the HTML is parsed, but before the DOMContentLoaded event.
  • Module Scope: Variables declared at the top level of an ES module are local to the module, not global to the window.
  • CORS for Local Files: When testing locally, you might encounter CORS errors if your module imports another local file. This is a browser security feature. Running a simple local web server (e.g., npx serve or Python’s http.server) can resolve this.
  • Bare Module Specifiers: Browsers do not support “bare” import specifiers like import { someFunc } from 'lodash';. You need to provide a full or relative path: import { someFunc } from './node_modules/lodash/lodash.js'; This is why bundlers like Webpack or Rollup are popular for browser development, as they resolve these paths and package dependencies.

Fix for Node.js Environments

In Node.js, you have two primary ways to enable ESM syntax:

  1. Using "type": "module" in package.json (Recommended for new projects):
    This is the modern and recommended approach for Node.js projects using ESM. Add the "type": "module" field to your package.json file. This tells Node.js to interpret all .js files within that package as ES modules by default.

    package.json:
    json
    {
    "name": "my-esm-app",
    "version": "1.0.0",
    "description": "A Node.js app using ESM",
    "main": "index.js",
    "type": "module", <-- Add this line
    "scripts": {
    "start": "node index.js"
    }
    }
    Now, your index.js (and other .js files) can freely use import and export:

    index.js:
    “`javascript
    import { greet } from ‘./utils.js’;

    console.log(greet(‘World’));
    “`

    utils.js:
    javascript
    export function greet(name) {
    return `Hello, ${name}!`;
    }

    Mixing with CommonJS: If you have CommonJS files in a project where "type": "module" is set, you must give them a .cjs extension.

  2. Using .mjs File Extension:
    If you don’t want to set "type": "module" for your entire project (e.g., in a mixed codebase or older project), you can use the .mjs file extension for individual files that use ESM syntax. Node.js will automatically interpret .mjs files as ES modules.

    index.mjs:
    “`javascript
    import { greet } from ‘./utils.mjs’; // Or ‘./utils.js’ if utils.js is also ESM

    console.log(greet(‘Node.js ESM’));
    “`

    utils.mjs:
    javascript
    export function greet(name) {
    return `Hello, ${name}!`;
    }
    Similarly, CommonJS files can use a .cjs extension to ensure they are treated as CommonJS modules.

Important Considerations for Node.js ESM:

  • __dirname and __filename: These CommonJS globals are not available in ES modules. You can achieve similar functionality using import.meta.url and Node.js’s url module:
    “`javascript
    import { fileURLToPath } from ‘url’;
    import { dirname } from ‘path’;

    const __filename = fileURLToPath(import.meta.url);
    const __dirname = dirname(__filename);
    * **`require()` vs. `import`:** You cannot directly use `require()` within an ES module. If you need to load a CommonJS module from an ES module, use an asynchronous `import()`:javascript
    // In an ES module
    const { someFunction } = await import(‘commonjs-package’);
    ``
    Conversely, CommonJS modules cannot use    import` directly.

Advanced Scenarios and Best Practices

  • Bundlers (Webpack, Rollup, Parcel): For complex browser applications, especially those using external NPM packages, a JavaScript bundler is almost essential. Bundlers handle module resolution (including bare specifiers), transpilation (e.g., converting modern JavaScript to older versions for wider browser support), and optimization. They allow you to write your code using import/export and then bundle it into a format compatible with browsers.
  • Transpilers (Babel): If you need to use cutting-edge JavaScript features (including ESM) in environments that don’t fully support them, Babel can transpile your code into a compatible version. Bundlers often integrate Babel.
  • TypeScript: If you’re using TypeScript, module resolution is configured in tsconfig.json. The module and moduleResolution options dictate how TypeScript handles import and export statements and how it generates JavaScript output. Setting module: "ESNext" or module: "Node16" (or later) and moduleResolution: "Node" or moduleResolution: "bundler" are common for modern projects.

Conclusion

The “Cannot use import statement outside a module” error is a signal that your JavaScript environment isn’t correctly interpreting your import/export syntax. By understanding the different module systems and configuring your HTML or Node.js package.json appropriately, you can easily resolve this issue. For larger projects, especially in the browser, leveraging bundlers and transpilers will provide the most robust and flexible solution for modern JavaScript development.

滚动至顶部