How to fix SyntaxError: Cannot use import statement outside a module in Node.js

The most common and recommended solution is to add "type": "module" to your package.json file. This tells Node.js to treat all .js files in your project as ES modules:

{
  "name": "your-project",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  }
}

After adding this field, restart your application. All .js files will now be interpreted as ES modules, allowing you to use import and export statements freely.

Important: If you have existing CommonJS files that use require(), you'll need to either convert them to ES modules or rename them with a .cjs extension.

If you don't want to change your entire project to ES modules, you can use the .mjs extension for individual files that need ES module syntax:

# Rename your file
mv index.js index.mjs

Then run it normally:

node index.mjs

Node.js automatically recognizes .mjs files as ES modules, regardless of the package.json "type" field. This approach is useful when you want to gradually migrate to ES modules or maintain a mixed codebase.

Note: When importing local files in .mjs files, you must include the file extension:

// Correct
import { myFunction } from './utils.mjs';

// Incorrect - will fail
import { myFunction } from './utils';

If you need to stick with CommonJS (for example, due to compatibility requirements), convert your import statements to require():

Before (ES modules):

import express from 'express';
import { readFile } from 'fs/promises';

export function handler() {
  // ...
}

After (CommonJS):

const express = require('express');
const { readFile } = require('fs/promises');

function handler() {
  // ...
}

module.exports = { handler };

This approach works immediately without any configuration changes but means you won't be using modern ES module features.

ES modules require Node.js version 12 or higher (with 13.2+ recommended for stable support). Check your Node.js version:

node --version

If you're on an older version, update Node.js:

# Using nvm (recommended)
nvm install 20
nvm use 20

# Or download from nodejs.org
# https://nodejs.org/

Node.js 20 LTS and above have excellent ES module support and are recommended for new projects.

If you're encountering this error in tests, configure your test runner to handle ES modules. For Jest, create or update jest.config.js:

export default {
  testEnvironment: 'node',
  transform: {},
  extensionsToTreatAsEsm: ['.ts'],
  moduleNameMapper: {
    '^(\.{1,2}/.*)\.js$': '$1'
  }
};

You may also need to add --experimental-vm-modules flag:

{
  "scripts": {
    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
  }
}

For Vitest (which has better ES module support):

// vitest.config.js
export default {
  test: {
    environment: 'node'
  }
};

Consider switching to Vitest if you're starting a new project, as it's designed with ES modules in mind.