JavaScriptモジュール設計がアプリの命運を分ける！ESM時代のアーキテクチャ入門

JavaScriptモジュール設計がアプリの命運を分ける！ESM時代のアーキテクチャ入門

JavaScriptで大規模なアプリケーションを構築する際、モジュールシステムをどう設計するかは、プロジェクト全体の命運を分ける最初の大きな決断となる。かつてのJavaScriptにはグローバルスコープしか存在せず、複数のスクリプトが互いの変数を上書きしてしまうリスクが常に付きまとっていた。

現代のモジュールシステムは、単にコードを複数のファイルに分割するための仕組みではない。それはシステムの各パーツの間に「境界線」を引き、依存関係の流れを制御するためのアーキテクチャそのものだ。適切な設計がなされていないモジュール構造は、プロジェクトが成長するにつれてメンテナンスを困難にし、変更のたびに予期せぬ場所でバグを発生させる原因となる。

この記事では、現代の標準であるESM（ECMAScript Modules）の特性を理解し、クリーンアーキテクチャの原則をモジュール設計にどう適用すべきかを詳しく解説していく。技術に詳しい同僚からアドバイスを受けるような感覚で、保守性の高いコードベースを構築するためのヒントを掴んでほしい。

モジュールシステムは「境界線」のデザインだ

JavaScriptのモジュールシステムには、主にCommonJS（CJS）とECMAScript Modules（ESM）の2つの流れがある。CommonJSはNode.jsの誕生とともに普及したサーバーサイド向けの仕組みであり、ESMはブラウザでもネイティブに動作するよう設計された現在の標準規格だ。これら2つは単に構文が異なるだけでなく、根本的な設計思想に大きな違いがある。

ESMがCommonJSから引き継がなかった「柔軟性」の正体

CommonJSの最大の特徴は、require()が通常の関数として実行される点にある。これにより、if文の中やループの中で動的にモジュールを読み込むことが可能だった。一方でESMは、import文を必ずファイルの先頭（トップレベル）に記述しなければならず、パスも静的な文字列である必要がある。この制約は一見不便に思えるが、実は「静的解析」を可能にするための意図的な設計だ。

ESMの制約のおかげで、ビルドツールはコードを実行することなく、どのモジュールがどこで使われているかを完全に把握できる。これが「Tree-shaking（ツリーシェイキング）」と呼ばれる、不要なコードを自動的に削除してバンドルサイズを削減する技術を支えている。CommonJSでは実行時まで依存関係が確定しないため、ツールは安全のために「使われていないかもしれないコード」もすべて含めざるを得ない。ESMは柔軟性を犠牲にすることで、パフォーマンスの最適化を手に入れたのだ。

このデモは、モジュールシステムの進化によって、どのように解析のしやすさが向上したかを視覚化したものだ。

クリーンアーキテクチャに学ぶ依存関係のルール

プロジェクトの規模が大きくなると、どのファイルがどのファイルを参照しているかが複雑に絡み合い、いわゆる「スパゲッティコード」になりがちだ。これを防ぐための有力な指針として、ロバート・マーチン氏が提唱した「クリーンアーキテクチャ」がある。すべてのプロジェクトに導入すべき銀の弾丸ではないが、モジュールの境界線を引く際の強力な土台となる。

依存の方向は常に「内側」へ

クリーンアーキテクチャの核心は「依存性のルール」にある。これは、システムの各パーツを同心円状のレイヤーに分け、依存の方向を一方向に限定するというルールだ。円の内側にはビジネスロジック（システムの核心となるルール）を配置し、外側にはUI、データベース、フレームワークなどの技術的な詳細を配置する。

重要なのは、内側のレイヤーは外側のレイヤーについて何も知らないという点だ。たとえば、ユーザー登録のルール（ビジネスロジック）を記述したモジュールの中で、Reactの特定の関数や、特定のデータベース操作用のライブラリを直接インポートしてはいけない。なぜなら、技術スタックはビジネスルールよりも頻繁に変更されるからだ。技術に依存しない「コア」を保つことで、フレームワークの乗り換えやライブラリのアップデートに強いシステムが構築できる。

このデモは、依存関係が常にシステムの核心（ビジネスロジック）に向かって流れるべきであることを示している。外側の層を変更しても、内側の層には影響が及ばない構造が理想的だ。

モジュールグラフで健康状態をチェックする

自分のプロジェクトが健全な依存関係を保てているかどうかを確認するには、「モジュールグラフ」を可視化するのが効果的だ。モジュールグラフとは、ファイル同士のインポート関係を線で結んだネットワーク図のことである。MadgeやDependency Cruiserといったツールを使えば、現在のコードベースから自動的にこのグラフを生成できる。

循環参照と「やりすぎた共通ユーティリティ」の罠

不健全なグラフには、いくつかの共通した特徴がある。その筆頭が「循環参照」だ。モジュールAがBをインポートし、BがCをインポートし、さらにCがAをインポートしているような状態を指す。これはモジュールの再利用を困難にするだけでなく、ビルドエラーや予期せぬ実行時の不具合を引き起こす温床となる。

また、utils.jsのような汎用的なファイルに何でも詰め込みすぎるのも危険だ。あらゆる場所から参照される巨大なユーティリティファイルは、その一部を修正しただけでシステム全体に影響が及ぶ「爆発半径」の大きな部品になってしまう。これを解決するには、単一責任の原則に基づき、ユーティリティを機能ごとに細かく分割し、特定の文脈に閉じた場所に配置し直す必要がある。高レベルのモジュールが低レベルのモジュールに依存するという原則を、グラフを通じて常に監視することが重要だ。

バレルファイル（index.js）の使用は慎重に

JavaScript開発でよく使われる手法に「バレルファイル」がある。これは、ディレクトリ内の複数のモジュールを一つのindex.js（またはindex.ts）でまとめて再エクスポートする仕組みだ。インポート側の記述がシンプルになり、ディレクトリ構造を隠蔽できるため、コードの見た目は非常に美しくなる。

見た目の美しさとパフォーマンスのトレードオフ

しかし、バレルファイルには無視できないデメリットがある。それは、ビルドパフォーマンスの低下とTree-shakingの阻害だ。バレルファイル経由で一つの関数だけをインポートしたつもりでも、ビルドツールはそのディレクトリ内のすべてのファイルを解析対象として読み込んでしまうことがある。

大規模なプロジェクトでは、この影響が顕著に現れる。実際にAtlassianのエンジニアリングチームは、Jiraのフロントエンドからバレルファイルを削除することで、ビルド時間を75%も短縮し、バンドルサイズの削減にも成功したと報告している。小規模なプロジェクトであれば利便性が勝るが、規模が拡大してきたら「インポートの美しさ」のために「実行性能」を犠牲にしていないか、立ち止まって考える必要があるだろう。

このデモで示しているように、バレルファイルは記述を簡潔にする一方で、裏側での解析コストを増大させる可能性がある。パフォーマンスが求められる現場では、直接的なインポートが推奨される場合も多い。

結合度をコントロールし保守性を高める

モジュール間の関係性を考える上で避けて通れないのが「結合度」という概念だ。結合度とは、あるモジュールが別のモジュールの内部実装にどれほど依存しているかを示す指標である。保守性の高いシステムを目指すなら、可能な限り「疎結合」な状態を保つことが求められる。

特に注意すべきは「密結合」と「暗黙的な結合」だ。密結合は、相手のモジュールの内部の仕組みを知りすぎている状態であり、一方を修正するともう一方も修正しなければならない「変更の連鎖」を引き起こす。一方、暗黙的な結合は、グローバルな状態（シングルトンやグローバル変数）を介して、目に見えない形で依存している状態だ。これらはデバッグを困難にし、コードの予測可能性を著しく低下させる。依存関係は常に明示的（Explicit）にし、モジュールが公開する「インターフェース」のみを通じてやり取りを行うのが、長期的な運用における鉄則だ。

この記事のポイント

• ESMは静的解析を可能にする制約を設けることで、Tree-shakingによる最適化を実現している
• クリーンアーキテクチャの原則に従い、依存の方向を常に「外側から内側のビジネスロジック」へ向ける
• モジュールグラフを可視化し、循環参照や肥大化したユーティリティファイルを早期に発見・解消する
• バレルファイルは小規模では便利だが、大規模開発ではビルド時間やバンドルサイズに悪影響を与える可能性がある
• 結合度を低く保ち、モジュール間のやり取りを明示的なインターフェースに限定することで保守性を高める

海田 洋祐

・ 複数業界における17年間のデジタルビジネス開発経験
・ ウェブサイト開発のためのHTML、PHP、CSS、Java等の実用的知識
・ 15ヶ国語対応の多言語SaaSの開発経験
・ 17年間にも及ぶ、Eコマース長期運営経験
・ 幅広い業界でのSEO最適化の豊富な経験