What Are ES Modules? Import and Export Explained for AI-Assisted Developers

Every AI-generated project splits code across files using import and export. Here's what that means and what to do when it breaks.

Why AI Coders Need to Know This

The moment your project grows beyond one file, you need modules. AI will create 10, 20, 50 files and connect them with import/export. When a module error appears, it stops everything:

• "Cannot use import statement outside a module"
• "SyntaxError: Unexpected token 'export'"
• "Module not found: Error: Can't resolve './utils'"

These errors are almost never about the logic in your code. They're about how the module system is configured. Knowing the basics of ES Modules turns a 2-hour debugging session into a 2-minute fix.

Real Scenario

This produces multiple files connected via imports — the most common module pattern in any real project.

What AI Generated

// ---- utils/formatters.js ----

// Named export: a specific function with a name
export function formatDate(dateString) {
  const date = new Date(dateString);
  return date.toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long', 
    day: 'numeric'
  });
}

// Named export: another function from the same file
export function formatCurrency(amount, currency = 'USD') {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency
  }).format(amount);
}

// Default export: the "main thing" this file provides
export default function formatPercent(value) {
  return `${(value * 100).toFixed(1)}%`;
}


// ---- App.js ----

// Import named exports — must use their exact names in { }
import { formatDate, formatCurrency } from './utils/formatters';

// Import default export — name it whatever you want
import formatPercent from './utils/formatters';

// Or import everything in one line:
import formatPercent, { formatDate, formatCurrency } from './utils/formatters';

function App() {
  const price = formatCurrency(1299.99);       // "$1,299.99"
  const date = formatDate('2026-03-17');        // "March 17, 2026"
  const growth = formatPercent(0.127);          // "12.7%"

  return (
    <div>
      <p>Price: {price}</p>
      <p>Date: {date}</p>
      <p>Growth: {growth}</p>
    </div>
  );
}

export default App;

Understanding Each Part

Named exports: export function / export const

A named export makes a specific binding available for other files to import. You can have as many named exports per file as you want. When importing, the names must match exactly and go inside curly braces: import { formatDate } from './utils/formatters'.

Default export: export default

A file can have one default export — its primary value. When importing a default, you don't use curly braces and you can choose any name: import whatever from './myFile'. React components are almost always default exports.

The import path

./utils/formatters is a relative path — starting from the current file's location. The ./ means "same folder." ../ goes up one folder. Paths without ./ or ../ (like import React from 'react') refer to packages in node_modules.

Named vs. default: when to use which

• Default export: One main thing per file — a React component, a class, a configuration object.
• Named exports: Multiple utilities, helpers, or constants from the same file.
• Barrel files: AI often creates an index.js file that re-exports from multiple files so you can import from a single path: import { formatDate, formatCurrency } from './utils'.

CommonJS vs. ESM

There are two module systems in JavaScript. ES Modules (the modern standard) use import/export. CommonJS (Node.js's original system) uses require()/module.exports. They don't mix in the same file. Most AI-generated code uses ESM, but some older packages and Node.js scripts still use CommonJS.

The type: "module" in package.json

Node.js defaults to CommonJS. To use import/export in Node.js without a bundler, you need to add "type": "module" to your package.json, or use the .mjs file extension. React projects created with Vite or Create React App configure this automatically.

What AI Gets Wrong

How to Debug with AI

"Cannot use import statement outside a module"

This is the most common module error in Node.js. Debugging prompt: "I'm getting 'Cannot use import statement outside a module' in a Node.js script. My package.json does not have type: module. Should I add it, or convert my imports to require()?"

"Module not found: Can't resolve './filename'"

Path problem. Debugging prompt: "I'm getting Module not found for './utils/formatters'. My file is at src/components/App.js and formatters.js is at src/utils/formatters.js. What is the correct relative import path from App.js?"

Tool-specific tips

• Cursor: Ask it to show you the directory structure and confirm the import paths are correct relative to each file's location.
• Claude Code: Paste the error + both file paths. Ask: "Is this a named export or default export, and am I importing it correctly?"
• Windsurf: Good at converting entire projects from CommonJS to ESM or vice versa when you change the module strategy.

What to Learn Next

• What Is npm? — Packages you install via npm are imported with the same import syntax as your own files.
• What Is JavaScript? — The language foundation that modules build on.
• What Is a Package Manager? — How npm and the node_modules folder relate to your import paths.
• What Are Environment Variables? — Modules are where you import your env config; understanding both together is essential.

FAQ