概要
モジュールとは「処理の塊」ではない。
それは責務の単位であり、他との依存関係をコントロールする構造上の境界線である。
本稿では、JavaScriptにおけるモジュール設計を以下の視点から体系化する：
- ESModules vs CommonJS の根本的違い
- export/import構文の設計ルール
- 分割と責務の境界定義
- 依存関係の明示的設計
- ルートエントリと内部構造の整理
1. ESModules vs CommonJS：構文と動作の差異
| 特性 | ESModules (ESM) | CommonJS (CJS) |
|---|---|---|
| 構文 |
import / export
|
require() / module.exports
|
| 実行タイミング | 静的（パース時に解決） | 動的（実行時に解決） |
| 拡張子 |
.mjs / .js（type:module） |
.cjs / .js（type:commonjs） |
| top-level await | ✅ 可能 | ❌ 不可 |
✅ ESMが主流だが、Node.jsとの互換性ではCJSが未だ根強い
→ プロジェクト開始時点でESM / CJSどちらを使うかを明示すべき
2. モジュールの構成原則：意味単位での分割
project/
├─ modules/
│ ├─ user/
│ │ ├─ index.ts
│ │ ├─ service.ts
│ │ └─ validator.ts
│ ├─ auth/
│ │ ├─ index.ts
│ │ └─ session.ts
- ✅ モジュールは機能（feature）単位で分割
- ❌ utils や common のような横断的な名目だけでまとめない
3. export戦略：構造を公開するか抽象化するか
// user/index.ts
export { getUser, updateUser } from './service';
export { validateUser } from './validator';
- ✅
index.tsで公開APIを整理することで外部依存をコントロール - ✅ 内部構造を隠蔽し、意図されたエントリポイントのみ公開
4. 依存関係の設計と制御
- ✅ モジュール → サブモジュールの一方向依存を維持
- ❌ 循環依存（A→B→A）は構造崩壊の原因
- ✅ 共通依存（例：logger / config）はDI（依存注入） or Adapter層に隔離する
// NG
userService → config → userService
// OK
userService → configAdapter → config
5. ESM特有の import/export パターン
// 名前付きエクスポート
export function hello() {}
// デフォルトエクスポート
export default function () {}
// インポート側
import { hello } from './module';
import main from './module';
→ ✅ 名前付きで意図を明示、defaultは1モジュール = 1主要機能がある場合のみ使用
6. top-level await と構造化非同期
// ESMのみで使える構文
const data = await fetchData();
- ✅ 非同期初期化ロジックをmainエントリで直書き可能
- ✅ setup用モジュールとして
.bootstrap.tsのような命名を採用する例も多い
設計判断フロー
① 実行環境はNode.jsかブラウザか？ → ESM/CJSの選択
② 機能単位で責務が切れているか？ → modules/ を構造で分割
③ エクスポートする構造は抽象化されているか？ → index.tsの活用
④ 依存関係に循環はないか？ → 一方向 & Adapter層を設計
⑤ 非同期初期化はどこに書く？ → top-level await または明示的setup関数に分離
よくあるミスと対策
❌ util.js に全処理をまとめて import で吸い上げ
→ ✅ 意味単位のモジュールに分割し、単一責務の原則を適用
❌ デフォルトエクスポートが多用され、関数の意図が読めない
→ ✅ 名前付きエクスポートで意図を構文で明示
❌ 内部構造まで全部exportし、外部モジュールからの依存が崩壊
→ ✅ index.tsで公開するインターフェースを制限・統制する
結語
モジュールとは、再利用ではなく、“意味の境界線を設計する”ための構造である。
- 責務ごとに構造を切り
- エクスポートは意図を明示し
- 依存を一方向に制御する
JavaScriptにおけるモジュール設計とは、
「プロジェクトの破綻を防ぐための、構造と言語による契約」である。