Node.jsモジュール入門 - CommonJSとES Modulesの違いを理解する

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// mathUtils.js（CommonJS形式）

// 関数を定義
function add(a, b) {
  return a + b;
}

function subtract(a, b) {
  return a - b;
}

// module.exportsでエクスポート
module.exports = {
  add,
  subtract,
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// main.js（CommonJS形式）

// モジュールの読み込み
const mathUtils = require('./mathUtils');

// 関数の使用
console.log(mathUtils.add(2, 3));      // 5
console.log(mathUtils.subtract(5, 2)); // 3

// 分割代入で個別に取得することも可能
const { add, subtract } = require('./mathUtils');
console.log(add(10, 5)); // 15

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// 正しい使い方
exports.add = (a, b) => a + b;
exports.subtract = (a, b) => a - b;

// 誤った使い方（動作しない）
exports = {
  add: (a, b) => a + b,
};
// この場合、module.exportsとの参照が切れるため、
// require()しても空オブジェクトが返される

1
2
3
4
5
6

// 動的な読み込みの例
const moduleName = process.env.NODE_ENV === 'production'
  ? './prodConfig'
  : './devConfig';

const config = require(moduleName);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// mathUtils.mjs（ES Modules形式）

// 名前付きエクスポート
export function add(a, b) {
  return a + b;
}

export function subtract(a, b) {
  return a - b;
}

// 定数のエクスポート
export const PI = 3.14159;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// main.mjs（ES Modules形式）

// 名前付きインポート
import { add, subtract, PI } from './mathUtils.mjs';

console.log(add(2, 3));      // 5
console.log(subtract(5, 2)); // 3
console.log(PI);             // 3.14159

// 別名でインポート
import { add as sum } from './mathUtils.mjs';
console.log(sum(10, 20)); // 30

// すべてをまとめてインポート
import * as math from './mathUtils.mjs';
console.log(math.add(1, 2)); // 3

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Calculator.mjs

export default class Calculator {
  add(a, b) {
    return a + b;
  }

  subtract(a, b) {
    return a - b;
  }
}

1
2
3
4
5
6
7

// main.mjs

// デフォルトインポート（任意の名前を付けられる）
import Calculator from './Calculator.mjs';

const calc = new Calculator();
console.log(calc.add(5, 3)); // 8

1
2
3

// 動的インポート（ES Modules）
const moduleName = './dynamicModule.mjs';
const module = await import(moduleName);

1
2
3
4
5

{
  "name": "my-esm-project",
  "version": "1.0.0",
  "type": "module"
}

1
2
3
4
5
6
7
8

{
  "name": "modern-nodejs-project",
  "version": "1.0.0",
  "type": "module",
  "engines": {
    "node": ">=20.0.0"
  }
}

1
2
3
4

{
  "name": "esm-project",
  "type": "module"
}

1
2
3
4
5

// config.cjs（CommonJS形式で記述）
module.exports = {
  port: 3000,
  host: 'localhost',
};

1
2
3
4
5
6
7
8

// server.js（ES Modules形式）
import { createRequire } from 'node:module';

// ES Modules内でrequireを使用するためのヘルパー
const require = createRequire(import.meta.url);
const config = require('./config.cjs');

console.log(config.port); // 3000

1
2
3
4
5

// legacy.cjs（CommonJS）
module.exports = {
  greet: (name) => `Hello, ${name}!`,
  version: '1.0.0',
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// main.mjs（ES Modules）
// デフォルトインポートでmodule.exportsを取得
import legacy from './legacy.cjs';

console.log(legacy.greet('World')); // Hello, World!
console.log(legacy.version);        // 1.0.0

// 名前付きインポートも可能（静的解析による推測）
import { greet } from './legacy.cjs';
console.log(greet('Node.js')); // Hello, Node.js!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// modern.mjs（ES Modules、トップレベルawaitなし）
export function calculate(x) {
  return x * 2;
}

export default class Calculator {
  multiply(a, b) {
    return a * b;
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// main.cjs（CommonJS）
// ES Modulesをrequireで読み込む（Node.js 20+）
const modern = require('./modern.mjs');

console.log(modern);
// [Module: null prototype] {
//   calculate: [Function: calculate],
//   default: [class Calculator]
// }

console.log(modern.calculate(5)); // 10

const Calculator = modern.default;
const calc = new Calculator();
console.log(calc.multiply(3, 4)); // 12

1
2
3

// asyncModule.mjs（トップレベルawaitを含む）
const data = await fetch('https://api.example.com/data');
export const result = await data.json();

1
2
3
4
5
6
7
8

// main.cjs（CommonJS）
// 非同期ESMは動的import()で読み込む
async function main() {
  const { result } = await import('./asyncModule.mjs');
  console.log(result);
}

main();

1
2
3
4
5
6
7

// ES ModulesでのJSONインポート
import packageJson from './package.json' with { type: 'json' };
console.log(packageJson.name);

// ES Modulesでの__dirnameの代替
console.log(import.meta.dirname);  // /path/to/directory
console.log(import.meta.filename); // /path/to/file.mjs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "name": "esm-project",
  "version": "1.0.0",
  "type": "module",
  "engines": {
    "node": ">=20.0.0"
  },
  "exports": {
    ".": {
      "import": "./src/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "start": "node src/index.js",
    "build": "tsc"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "name": "dual-package-library",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}