Without modules (global scope hell):
────────────────────────────────────
var user = "Alice";       // global.js
var user = "Bob";         // orders.js — 💥 OVERWROTE user!
console.log(user);        // "Bob" — introduced a bug!

With modules (encapsulated scope):
───────────────────────────────────
// user.js — exports a value
export const user = "Alice";

// orders.js — has its own scope
const user = "Bob"; // Only exists inside orders.js!

CommonJS project wants to use an ESM-only library:

  const pkg = require('esm-only-pkg');
  // ⛔ Error [ERR_REQUIRE_ESM]: require() of ES Module not supported!

  You now need to:
  - Convert your entire project to ESM, OR
  - Use dynamic import(), OR
  - Find a CJS-compatible alternative

This is the most common frustration for Node.js developers today.

COMMON JS (require)
══════════════════════

┌─────────────────────────────────────┐
│  main.js                            │
│                                     │
│  const math = require('./math');    │
│  │                                  │
│  ▼ Synchronous, runtime              │
│                                     │
│  1. Read math.js from disk           │
│  2. Execute all code in math.js      │
│  3. Grab module.exports              │
│  4. Assign to `math`                 │
│  5. Continue execution               │
└─────────────────────────────────────┘

ES MODULES (import)
══════════════════════

┌─────────────────────────────────────┐
│  main.js                            │
│                                     │
│  import { add } from './math.js';   │
│  │                                  │
│  ▼ Static, parse time                │
│                                     │
│  1. Parse all imports FIRST          │
│  2. Fetch math.js (before main runs) │
│  3. Parse math.js, find exports      │
│  4. Link imports to exports          │
│  5. Execute all code in order        │
│  6. Make `add` available             │
└─────────────────────────────────────┘

flowchart TB
    subgraph CJS["CommonJS (require)"]
        CJSStart["main.js starts"] --> CJSReq["require('./math')"]
        CJSReq --> CJSSync["⏺ Synchronously read\nand execute math.js"]
        CJSSync --> CJSMod["module.exports = { add, subtract }"]
        CJSMod --> CJSDone["Use math.add(2,3)"]

        CJSReqDynamic["Dynamic:\nrequire() can be\ncalled anywhere,\nconditionally"]
    end

    subgraph ESM["ES Modules (import)"]
        ESMStart["Parse main.js"] --> ESMFind["Find import statements"]
        ESMFind --> ESMFetch["📥 Fetch math.js (async)"]
        ESMFetch --> ESMParse["Parse math.js\nFind exports"]
        ESMParse --> ESMLink["🔗 Link imports to exports\n(static binding)"]
        ESMLink --> ESMExec["Execute all code"]
        ESMExec --> ESMDone["Use add(2,3)"]

        ESMStatic["Static:\nimport must be\nat top level"]
    end

    style CJS fill:#f59e0b,color:#fff
    style ESM fill:#10b981,color:#fff

flowchart TD
    Start["require('express')"] --> IsCore["Is it a core module?\n(fs, path, http...)"]
    IsCore -->|"Yes ✅"| ReturnBuiltin["Return built-in module"]
    IsCore -->|"No"| IsRelative["Starts with ./ or ../?"]
    IsRelative -->|"Yes"| RelativeResolve["Resolve relative to\n__filename"]
    IsRelative -->|"No"| NodeModules["Search node_modules/\nWalk up directory tree"]
    NodeModules --> Found["Found package.json?"]
    Found -->|"Yes"| PkgJson["Read package.json\nCheck 'main' field"]
    Found -->|"No"| WalkUp["Walk up to parent dir"]
    WalkUp --> NodeModules

    PkgJson --> IndexJS["Look for index.js"]
    IndexJS --> LoadModule["⏺ Load & execute module"]
    LoadModule --> Cache["Cache module.exports\n(modules are singletons!)"]
    Cache --> Return["Return module.exports"]

    RelativeResolve --> IndexJS

    style Start fill:#4f46e5,color:#fff
    style Cache fill:#10b981,color:#fff
    style Return fill:#059669,color:#fff

flowchart LR
    subgraph Phase1["1️⃣ Construction (Parse Time)"]
        P1["Find all import statements\n(static analysis)"]
        P1 --> P1Resolve["Resolve module specifiers\nto file URLs"]
        P1Resolve --> P1Fetch["Fetch module files\n(async, in parallel)"]
    end

    subgraph Phase2["2️⃣ Instantiation (Link Time)"]
        P2["Create module records"]
        P2 --> P2Link["Link exports to imports\n(create bindings, not values)"]
    end

    subgraph Phase3["3️⃣ Evaluation (Execution)"]
        P3["Execute module code\n(top to bottom)"]
        P3 --> P3Done["Live bindings update\nwhen exports change"]
    end

    Phase1 --> Phase2 --> Phase3

    style Phase1 fill:#4f46e5,color:#fff
    style Phase2 fill:#7c3aed,color:#fff
    style Phase3 fill:#059669,color:#fff

sequenceDiagram
    participant App as App.js
    participant Resolver as Node.js Module Resolver
    participant FileSys as File System
    participant Module as Loaded Module

    App->>Resolver: require('lodash')
    Resolver->>FileSys: Is 'lodash' a core module?
    FileSys-->>Resolver: No
    Resolver->>FileSys: Search ./node_modules/lodash
    FileSys-->>Resolver: Found!
    Resolver->>FileSys: Read package.json
    FileSys-->>Resolver: { "main": "lodash.js" }
    Resolver->>FileSys: Read lodash.js
    FileSys-->>Resolver: File content
    Resolver->>Module: Execute in a wrapper function
    Note over Module: (function(exports, require,<br/> module, __filename, __dirname) {<br/>  // your module code<br/>});
    Module-->>Resolver: module.exports = { ... }
    Resolver->>Resolver: Cache the result
    Resolver-->>App: ✅ Returns lodash object

    Note over App,Module: ─── Second require ───
    App->>Resolver: require('lodash') again
    Resolver->>Resolver: Already cached! Return immediately
    Resolver-->>App: ✅ Returns SAME object (singleton)

// ─── EXPORTING ──────────────────────────────────────

// method 1: Export individual properties
module.exports.add = (a, b) => a + b;
module.exports.subtract = (a, b) => a - b;

// method 2: Export a single value (overwrites module.exports)
module.exports = {
  add: (a, b) => a + b,
  subtract: (a, b) => a - b,
};

// method 3: Shorthand export
exports.add = (a, b) => a + b;   // ❗ exports !== module.exports
// exports = { add: ... } would BREAK the reference!

// ─── IMPORTING ──────────────────────────────────────
const math = require('./math');           // Full import
const { add, subtract } = require('./math'); // Destructured
const path = require('path');             // Core module
const express = require('express');       // npm package

// ─── DYNAMIC IMPORT (works in both CJS and ESM) ────
// ✅ Use dynamic import for conditionally loading modules

async function loadFormatter(locale) {
  if (locale === 'de') {
    // Dynamic import() — works everywhere
    const { format } = await import('./formatters/de.js');
    return format;
  } else {
    const { format } = await import('./formatters/en.js');
    return format;
  }
}

// ─── CJS: require vs import() compatibility ─────────
// In a CJS file, you can use import() to load ESM modules:
async function loadESMModule() {
  // ⛔ This FAILS: const eslint = require('eslint');
  // ✅ This WORKS:
  const eslint = await import('eslint');
  return eslint;
}

// ─── ESM: __dirname equivalent ──────────────────────
// In CJS, you have __dirname and __filename
// In ESM, you need to construct them:
import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log(__dirname);  // Works!

// package.json — Ship both CJS and ESM
{
  "name": "my-hybrid-package",
  "version": "1.0.0",
  "main": "./dist/cjs/index.js",       // CJS entry
  "module": "./dist/esm/index.js",      // ESM entry (bundlers)
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",  // ESM consumers
      "require": "./dist/cjs/index.js"  // CJS consumers
    },
    "./utils": {
      "import": "./dist/esm/utils.js",
      "require": "./dist/cjs/utils.js"
    }
  },
  "files": ["dist/"]
}

// src/index.js — Write in ESM, compile to both
export function add(a, b) { return a + b; }
export function multiply(a, b) { return a * b; }

// ─── Build script ───────────────────────────────────
// 1. Compile ESM: tsc src/ --outDir dist/esm --module esnext
// 2. Compile CJS: tsc src/ --outDir dist/cjs --module commonjs
// 3. Package.json handles routing consumers to the right format

// ─── Consumer usage ─────────────────────────────────
// CJS consumer:
const { add } = require('my-hybrid-package');  // ✅ Works

// ESM consumer:
import { add } from 'my-hybrid-package';        // ✅ Works

// ─── MIGRATION STRATEGY: CJS → ESM ──────────────────

// Step 1: Add to package.json
{
  "type": "module",                        // All .js files become ESM
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

// Step 2: Rename CJS-only files to .cjs
// config/database.cjs — Keep as CJS (uses module.exports)
module.exports = {
  host: process.env.DB_HOST,
  port: 5432,
};

// Step 3: Convert imports one-by-one
// BEFORE (CJS):
const express = require('express');
const { Pool } = require('pg');
const config = require('./config/database.cjs');
const { validateUser } = require('./middleware/validation');

// AFTER (ESM):
import express from 'express';
import pg from 'pg';
import config from './config/database.cjs';  // .cjs works in ESM!
import { validateUser } from './middleware/validation.js';  // Must include .js!
const { Pool } = pg;

// Step 4: Handle __dirname (not available in ESM)
// BEFORE:
const publicPath = path.join(__dirname, 'public');

// AFTER:
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const publicPath = join(__dirname, 'public');

// Step 5: Replace require.resolve()
// BEFORE: require.resolve('some-package')
// AFTER: import.meta.resolve('some-package')  // Node 20+

// Step 6: Handle dynamic requires
// BEFORE:
let validator;
if (process.env.VALIDATION === 'strict') {
  validator = require('./validators/strict');
} else {
  validator = require('./validators/loose');
}

// AFTER:
let validator;
if (process.env.VALIDATION === 'strict') {
  validator = await import('./validators/strict.js');
} else {
  validator = await import('./validators/loose.js');
}

// What you write (math.js):
const add = (a, b) => a + b;
module.exports = { add };

// What Node.js EXECUTES:
(function(exports, require, module, __filename, __dirname) {
  const add = (a, b) => a + b;
  module.exports = { add };

  // return module.exports;  ← implicit
});

// What you write (math.js):
export const add = (a, b) => a + b;

// What the ESM loader creates:
// Module Record:
// {
//   [[Module]]: {
//     add: <live binding to add variable>
//   },
//   [[RequestedModules]]: [],
//   [[Evaluated]]: false
// }

// ❌ MISTAKE 1: Forgetting .js extension in ESM imports
import { add } from './math';   // ❌ ERR: Cannot find module
import { add } from './math.js'; // ✅ Correct!

// ❌ MISTAKE 2: Using require() on ESM-only packages
const chalk = require('chalk');  // ❌ ERR_REQUIRE_ESM
const chalk = await import('chalk'); // ✅ Use dynamic import

// ❌ MISTAKE 3: Circular dependencies in CJS (returns partial object)
// a.js: const b = require('./b');  // Gets a partial object!
// b.js: const a = require('./a');  // Gets a partial object!
// ✅ FIX: Restructure to avoid circular deps, or use lazy require()

// ❌ MISTAKE 4: Overriding exports reference
exports = { add: (a, b) => a + b };  // ❌ Breaks the reference!
module.exports = { add: (a, b) => a + b }; // ✅ Correct!

// ❌ MISTAKE 5: Using import inside conditionals (ESM)
if (condition) {
  import { add } from './math.js'; // ❌ SyntaxError: Unexpected token
}
// ✅ Use dynamic import() for conditional loading
if (condition) {
  const { add } = await import('./math.js'); // ✅ Works!
}

// ❌ MISTAKE 6: Mixing require and import in the same .js file
// Only possible with special flags or .mjs/.cjs separation

import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// router.js — ESM version
export async function loadRoute(path) {
  // Dynamically import the matching route handler
  // e.g., /users → import('./routes/users.js')
  // e.g., /products → import('./routes/products.js')
}

// === app.js (CommonJS) ===
const { getLogger } = require('./logger');
console.log(getLogger()); // 💥 TypeError: getLogger is not a function

// === logger.js ===
function getLogger() {
  return {
    info: (msg) => console.log(`[INFO] ${msg}`),
    error: (msg) => console.log(`[ERROR] ${msg}`),
  };
}

exports = { getLogger };  // ← BUG!

// ─── COMMONJS ───────────────────────────────────────
module.exports = { foo };      // Export
exports.bar = bar;             // Export (shorthand)
const x = require('./foo');     // Import
const { a, b } = require('./x');// Destructured import

// ─── ES MODULES ─────────────────────────────────────
export const foo = 1;           // Named export
export default Foo;             // Default export
export { foo as bar };          // Rename export
import { foo } from './foo.js'; // Named import
import Foo from './foo.js';     // Default import
import * as X from './foo.js';  // Namespace import
import('./foo.js');             // Dynamic import

// ─── FILE EXTENSION RULES ───────────────────────────
// .js → ESM if "type": "module", else CJS
// .mjs → Always ESM
// .cjs → Always CommonJS

// ─── ESM UTILITIES ──────────────────────────────────
import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// ─── PACKAGE.JSON EXPORTS ───────────────────────────
{
  "exports": {
    "import": "./dist/esm/index.js",
    "require": "./dist/cjs/index.js"
  }
}