search
Javascript star Featured

[SOLVED] Cannot use import statement outside a module Error in JavaScript

Learn how to fix the 'Cannot use import statement outside a module' error in JavaScript applications. This comprehensive guide covers ES6 modules, Node.js, and browser compatibility.

person By Gautam Sharma
calendar_today January 2, 2026
schedule 11 min read
JavaScript ES6 Modules import Node.js Error Frontend Backend

The ‘Cannot use import statement outside a module’ error is a common JavaScript issue that occurs when trying to use ES6 import statements in environments that don’t recognize ES6 modules. This error typically happens when using import/export syntax in Node.js without proper configuration or when browser scripts aren’t properly configured as modules.

This comprehensive guide explains what causes this error, why it happens, and provides multiple solutions to fix it in your JavaScript projects with clean code examples and directory structure.

What is the import statement outside a module Error?

The “Cannot use import statement outside a module” error occurs when:

  • Using ES6 import/export syntax in Node.js without proper configuration
  • Browser scripts don’t have type="module" attribute
  • Module system configuration issues
  • Mixing CommonJS and ES6 modules incorrectly
  • Legacy JavaScript environments that don’t support ES6 modules

Common Error Messages:

  • Cannot use import statement outside a module
  • SyntaxError: Cannot use import statement outside a module
  • import declarations may only appear at top level of a module
  • Unexpected token 'import'
  • Must use import to load ES Module

Understanding the Problem

ES6 modules require explicit configuration to work properly. Unlike CommonJS (which uses require()), ES6 modules need to be explicitly declared as modules in both Node.js and browser environments.

Typical JavaScript Project Structure:

my-js-app/
├── package.json
├── src/
│   ├── main.js
│   ├── utils/
│   │   ├── helpers.js
│   │   └── validators.js
│   ├── components/
│   │   └── app.js
│   └── styles/
├── public/
│   └── index.html
├── dist/
└── node_modules/

Solution 1: Configure package.json for ES6 Modules

The most common solution for Node.js projects is to configure package.json to use ES6 modules.

❌ Without Module Configuration:

// package.json - ❌ Missing type field
{
  "name": "my-js-app",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

✅ With Module Configuration:

package.json:

{
  "name": "my-js-app",
  "version": "1.0.0",
  "type": "module", // ✅ Enable ES6 modules
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "node --experimental-modules index.js"
  },
  "dependencies": {
    "express": "^4.18.0"
  }
}

src/utils/helpers.js:

// ✅ ES6 export syntax
export const formatDate = (date) => {
  return date.toLocaleDateString();
};

export const capitalize = (str) => {
  return str.charAt(0).toUpperCase() + str.slice(1);
};

export default {
  formatDate,
  capitalize
};

src/main.js:

// ✅ ES6 import syntax
import { formatDate, capitalize } from './utils/helpers.js';
import helpers from './utils/helpers.js';

// ✅ Use imported functions
const today = new Date();
console.log(formatDate(today));
console.log(capitalize('hello world'));
console.log(helpers.formatDate(today));

Solution 2: Use Script Type Module in HTML

For browser environments, use the type="module" attribute in script tags.

❌ Without Module Type:

<!-- ❌ This will cause the error -->
<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <div id="app"></div>
  <!-- ❌ Missing type="module" -->
  <script src="src/main.js"></script>
</body>
</html>

✅ With Module Type:

public/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My ES6 Module App</title>
</head>
<body>
  <div id="app"></div>
  <!-- ✅ Use type="module" for ES6 imports -->
  <script type="module" src="src/main.js"></script>
</body>
</html>

src/main.js:

// ✅ This will work with type="module"
import { App } from './components/app.js';
import { formatDate } from './utils/helpers.js';

// ✅ Use imported modules
const app = new App();
app.init();

const date = formatDate(new Date());
console.log('Current date:', date);

Solution 3: Use .mjs File Extension

Use .mjs extension for ES6 module files in Node.js.

❌ With .js Extension:

// ❌ .js files without "type": "module" in package.json
// helpers.mjs - This will work, but helpers.js won't with ES6 imports

✅ With .mjs Extension:

src/utils/helpers.mjs:

// ✅ .mjs files are treated as ES6 modules by default
export const add = (a, b) => {
  return a + b;
};

export const multiply = (a, b) => {
  return a * b;
};

export default {
  add,
  multiply
};

src/main.mjs:

// ✅ .mjs file importing from .mjs file
import { add, multiply } from './utils/helpers.mjs';
import math from './utils/helpers.mjs';

console.log('Addition:', add(5, 3));
console.log('Multiplication:', multiply(4, 6));
console.log('Default export:', math.add(10, 20));

Solution 4: Use CommonJS in Node.js (Alternative)

If you prefer CommonJS, use require() instead of import.

❌ Mixing Import and Require:

// ❌ Don't mix import and require in same file
import fs from 'fs'; // ❌ ES6 import
const path = require('path'); // ❌ CommonJS require

✅ Using CommonJS:

src/main.js:

// ✅ CommonJS syntax (no package.json type="module" needed)
const { formatDate, capitalize } = require('./utils/helpers.js');
const helpers = require('./utils/helpers.js');

// ✅ Use required modules
const today = new Date();
console.log(formatDate(today));
console.log(capitalize('hello world'));

src/utils/helpers.js:

// ✅ CommonJS exports
const formatDate = (date) => {
  return date.toLocaleDateString();
};

const capitalize = (str) => {
  return str.charAt(0).toUpperCase() + str.slice(1);
};

module.exports = {
  formatDate,
  capitalize
};

Solution 5: Configure Node.js with —loader Flag

Use Node.js flags to enable ES6 modules without changing package.json.

Command Line Configuration:

# ✅ Run with ES6 module support
node --experimental-modules src/main.js

# ✅ Or use the newer flag
node --input-type=module -e "import('./src/main.js')"

Solution 6: Use Babel for Transpilation

Use Babel to transpile ES6 modules to CommonJS for compatibility.

package.json:

{
  "name": "my-js-app",
  "version": "1.0.0",
  "scripts": {
    "build": "babel src --out-dir dist --extensions .js",
    "start": "node dist/main.js"
  },
  "dependencies": {
    "@babel/core": "^7.0.0",
    "@babel/preset-env": "^7.0.0",
    "@babel/node": "^7.0.0"
  }
}

.babelrc:

{
  "presets": [
    ["@babel/preset-env", {
      "targets": {
        "node": "current"
      }
    }]
  ],
  "plugins": [
    "@babel/plugin-transform-modules-commonjs"
  ]
}

Solution 7: Handle Mixed Module Systems

Properly handle projects that use both CommonJS and ES6 modules.

src/utils/compatibility.js:

// ✅ Handle both CommonJS and ES6 module systems
const formatDate = (date) => {
  return date.toLocaleDateString();
};

const capitalize = (str) => {
  return str.charAt(0).toUpperCase() + str.slice(1);
};

// ✅ Export for both systems
if (typeof module !== 'undefined' && module.exports) {
  // ✅ CommonJS
  module.exports = { formatDate, capitalize };
} else {
  // ✅ ES6 modules
  export { formatDate, capitalize };
}

Working Code Examples

Complete ES6 Module Project:

// src/components/app.js
export class App {
  constructor() {
    this.data = [];
  }

  async init() {
    try {
      // ✅ Import within function scope if needed
      const { fetchData } = await import('./dataService.js');
      this.data = await fetchData();
      this.render();
    } catch (error) {
      console.error('Failed to initialize app:', error);
    }
  }

  render() {
    const appContainer = document.getElementById('app');
    if (appContainer) {
      appContainer.innerHTML = `
        <div class="app">
          <h1>ES6 Module App</h1>
          <p>Data loaded: ${this.data.length} items</p>
          <div id="content"></div>
        </div>
      `;
    }
  }
}

// ✅ Default export
export default App;
// src/utils/helpers.js
export const formatDate = (date) => {
  return date.toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  });
};

export const formatNumber = (num) => {
  return new Intl.NumberFormat().format(num);
};

export const debounce = (func, wait) => {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
};

// ✅ Named exports
export { formatDate, formatNumber, debounce };
// src/main.js
import { App } from './components/app.js';
import { formatDate, formatNumber } from './utils/helpers.js';

// ✅ Use imported modules
const app = new App();
app.init();

// ✅ Use utility functions
const today = formatDate(new Date());
const largeNumber = formatNumber(1234567);
console.log('Today is:', today);
console.log('Large number:', largeNumber);

Browser HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>ES6 Module Example</title>
</head>
<body>
  <div id="app"></div>
  
  <!-- ✅ Use type="module" for ES6 imports -->
  <script type="module" src="src/main.js"></script>
  
  <!-- ✅ Alternative: inline module -->
  <script type="module">
    import { formatDate } from './src/utils/helpers.js';
    console.log('Current date:', formatDate(new Date()));
  </script>
</body>
</html>

Best Practices for Module Management

1. Choose One Module System

// ✅ Stick to one module system in a project
// Either ES6 modules OR CommonJS, not both

2. Use Proper File Extensions

// ✅ Use .js extension with package.json "type": "module"
// OR use .mjs extension for ES6 modules

3. Configure Build Tools Properly

// ✅ Configure webpack, rollup, or other build tools for ES6 modules
// Set up proper module resolution

4. Handle Dynamic Imports

// ✅ Use dynamic imports for code splitting
const loadFeature = async () => {
  const { Feature } = await import('./feature.js');
  return Feature;
};

Debugging Steps

Step 1: Check Package.json Configuration

# Verify package.json has "type": "module"
cat package.json | grep type

Step 2: Check File Extensions

# Verify .js files are properly configured
# Or use .mjs for ES6 modules

Step 3: Check HTML Script Tags

<!-- Verify script tags have type="module" -->
<script type="module" src="main.js"></script>

Step 4: Test in Different Environments

# Test in Node.js
node --version
node src/main.js

# Test in browser
# Open index.html in browser with dev tools

Common Mistakes to Avoid

1. Forgetting package.json Configuration

// ❌ Don't forget to add "type": "module" to package.json
{
  "name": "my-app",
  "version": "1.0.0"
  // ❌ Missing "type": "module"
}

2. Missing File Extensions in Imports

// ❌ Don't forget .js extension in ES6 imports
import { func } from './module'; // ❌ Missing .js

// ✅ Include file extensions
import { func } from './module.js'; // ✅ Correct

3. Mixing Module Systems

// ❌ Don't mix import and require in same file
import fs from 'fs';
const path = require('path');

4. Incorrect Script Tags

<!-- ❌ Don't forget type="module" -->
<script src="main.js"></script>

<!-- ✅ Correct -->
<script type="module" src="main.js"></script>

Performance Considerations

1. Use Tree Shaking

// ✅ Import only what you need
import { specificFunction } from 'library'; // ✅ Tree-shakable
// Instead of: import * as library from 'library';

2. Implement Code Splitting

// ✅ Use dynamic imports for code splitting
const loadFeature = async () => {
  const { Feature } = await import('./feature.js');
  return Feature;
};

Security Considerations

1. Validate Module Sources

// ✅ Only import from trusted sources
// Avoid dynamic imports from user input
const userInput = 'user-provided-string';
// ❌ Don't do: import(userInput);

2. Sanitize Dynamic Module Paths

// ✅ Validate dynamic module paths
function isValidModulePath(path) {
  return /^[a-zA-Z0-9/_-]+\.js$/.test(path);
}

Testing Module Systems

1. Unit Test ES6 Modules

// Using Jest or similar testing framework
import { formatDate } from '../src/utils/helpers.js';

describe('ES6 Modules', () => {
  test('should format date correctly', () => {
    const date = new Date('2023-01-01');
    const formatted = formatDate(date);
    expect(formatted).toBe('January 1, 2023');
  });
});

2. Test Dynamic Imports

test('should load modules dynamically', async () => {
  const module = await import('../src/utils/helpers.js');
  expect(module.formatDate).toBeDefined();
});

Alternative Solutions

1. Use SystemJS for Dynamic Loading

// ✅ SystemJS provides dynamic module loading
System.import('myModule').then(module => {
  // Use module
});

2. Use AMD (RequireJS) for Legacy Support

// ✅ AMD modules for legacy browser support
define(['lodash', 'moment'], function(_, moment) {
  // Module code
});

Migration Checklist

  • Add “type”: “module” to package.json (for Node.js)
  • Add type=“module” to script tags (for browsers)
  • Include .js extensions in import statements
  • Test in both Node.js and browser environments
  • Update build tools configuration
  • Run comprehensive tests
  • Update documentation for team members

Conclusion

The ‘Cannot use import statement outside a module’ error is a common JavaScript issue that occurs when ES6 module syntax is used without proper configuration. By following the solutions provided in this guide—whether through package.json configuration, proper script tags, file extensions, or build tool setup—you can ensure your JavaScript applications properly handle ES6 modules.

The key is to understand that ES6 modules require explicit configuration in both Node.js and browser environments. With proper module system setup, your JavaScript applications will be modern, maintainable, and follow current best practices.

Remember to choose one module system for your project, configure your environment properly, include file extensions in imports, and test thoroughly across different environments to ensure your applications are robust and compatible.

Gautam Sharma

About Gautam Sharma

Full-stack developer and tech blogger sharing coding tutorials and best practices

tag Youtube code Website work Store

Related Articles

Javascript

Fix: CORS policy: No 'Access-Control-Allow-Origin' Error in Node & Javascript

Learn how to fix the 'CORS policy: No Access-Control-Allow-Origin' error in JavaScript and Node.js applications. This comprehensive guide covers CORS configuration, headers, and best practices.

January 2, 2026
Javascript

Fix: document is not defined error in JavaScript

Learn how to fix the 'document is not defined' error in JavaScript applications. This comprehensive guide covers server-side rendering, Node.js, and browser compatibility.

January 2, 2026
Javascript

[FIXED]: localStorage is not defined error in JavaScript

Learn how to fix the 'localStorage is not defined' error in JavaScript applications. This comprehensive guide covers server-side rendering, Node.js, and browser compatibility.

January 2, 2026