TypeScriptでESModulesを使ってユーティリティ関数を効率的に共有する方法

TypeScriptにおいて、コードの再利用性とメンテナンス性を向上させるためには、ユーティリティ関数を効率的に共有することが重要です。JavaScriptの標準として広く採用されているESModules（ECMAScript Modules）は、モジュール間で関数や変数を簡単にエクスポートし、再利用するための強力な手段を提供します。本記事では、TypeScriptでESModulesを使ってユーティリティ関数を共有する方法を中心に、エクスポートとインポートの具体的な手順やその利点を詳しく解説します。これにより、効率的なコード構成と依存関係管理を理解でき、プロジェクト全体の開発をスムーズに進めることが可能になります。

ESModulesとは何か

ESModules（ECMAScript Modules）は、JavaScriptにおけるモジュールシステムの標準仕様です。従来のCommonJSとは異なり、ESModulesはモジュールの静的解析をサポートし、コードの実行前に依存関係を解析することが可能です。これにより、より効率的なパフォーマンスとスコープ管理が実現されます。

モジュールの概念

モジュールとは、特定の機能を独立したファイルとして切り出し、他のファイルからその機能を利用できる仕組みを指します。ESModulesでは、exportとimportのキーワードを使用して、関数や変数、クラスを別のファイルに渡すことができます。

ESModulesの特徴

• 静的解析：モジュールが実行される前に、依存関係が明確に解析されるため、ビルドやツールによる最適化が容易です。
• デフォルトエクスポートと名前付きエクスポート：複数の関数やオブジェクトをエクスポートできる名前付きエクスポートと、1つの主要機能をエクスポートするデフォルトエクスポートがあります。
• スコープの分離：各モジュールは独自のスコープを持ち、グローバルな汚染を防ぎます。

ESModulesは、モダンなJavaScript開発における標準であり、TypeScriptでも広く利用されています。次章では、TypeScriptプロジェクトでESModulesを利用するための設定方法について説明します。

TypeScriptでのESModulesの設定方法

TypeScriptでESModulesを使用するためには、プロジェクトの設定を正しく行う必要があります。ESModulesを利用するには、TypeScriptのコンパイラオプションを調整し、モジュール解決の仕組みを適切に設定することが重要です。

TypeScriptコンフィグファイル（tsconfig.json）の設定

TypeScriptのプロジェクト設定は、通常 tsconfig.json ファイルで管理されます。ESModulesを使うためには、このファイルの module オプションを esnext または ES2020 に設定します。これにより、TypeScriptコンパイラがESModules形式でモジュールを扱うようになります。

{
  "compilerOptions": {
    "module": "esnext",
    "target": "es6",
    "moduleResolution": "node"
  }
}

主要オプションの説明

• module: “esnext”または”ES2020″に設定することで、ESModulesのサポートが有効になります。
• target: “es6″以上を指定することで、ESModulesに対応したJavaScriptにトランスパイルされます。
• moduleResolution: “node”を指定することで、Node.jsのモジュール解決ルールを使用します。

ブラウザ環境での設定

ブラウザ環境でESModulesを使用する場合、scriptタグに type="module" を指定することで、モジュールの読み込みが可能になります。

<script type="module" src="main.js"></script>

バンドラーツールの利用

ESModulesを使用する場合、WebpackやRollupなどのバンドラーツールと組み合わせて、複数のモジュールを1つのファイルにまとめることが一般的です。これにより、ブラウザやサーバー環境でのパフォーマンスが向上します。

次章では、ユーティリティ関数を定義し、ESModulesを使って他のモジュールと共有する具体的なメリットについて詳しく解説します。

ユーティリティ関数の定義と共有のメリット

ユーティリティ関数は、特定のタスクや操作を効率的に処理するために作成された汎用的な関数です。これらの関数は、プロジェクト全体で再利用されることが多く、コードの可読性や保守性を向上させるために、適切にモジュール化し、共有することが重要です。TypeScriptでESModulesを活用することで、これらの関数を効率的にエクスポート・インポートし、プロジェクトの複数ファイル間で簡単に共有することができます。

ユーティリティ関数を共有するメリット

ユーティリティ関数をモジュール化して共有することで、以下のようなメリットがあります。

再利用性の向上

ユーティリティ関数を別ファイルに分けることで、他の部分でも簡単に使い回すことができます。新しい機能や異なるモジュールにおいても、同じ関数を呼び出すだけで処理が完了するため、重複したコードを書く必要がなくなります。

保守性の向上

関数が1箇所にまとまっていると、バグ修正や機能追加が容易になります。変更を1つのファイルで行うだけで、すべての依存モジュールに反映されるため、更新作業が効率的に進みます。

コードの分割と整理

ユーティリティ関数を独立したモジュールに分割することで、各ファイルが責務を明確にし、コード全体がシンプルになります。これにより、コードの可読性が向上し、他の開発者がプロジェクトに参加した際にも理解しやすくなります。

実際のユーティリティ関数の例

例えば、数値の配列から最大値を取得する簡単なユーティリティ関数を考えます。この関数を一度定義しておけば、プロジェクト全体で利用できます。

// utils/math.ts
export function getMax(numbers: number[]): number {
  return Math.max(...numbers);
}

この関数は、どのモジュールからでもインポートすることで利用可能です。次章では、このような関数をESModulesを用いてエクスポートする具体的な手順について説明します。

実際に関数をエクスポートする手順

TypeScriptでユーティリティ関数を定義し、他のファイルやモジュールで再利用できるようにするためには、exportキーワードを使って関数をエクスポートする必要があります。ESModulesを活用すれば、必要な関数や変数を簡単に外部に公開することができます。ここでは、実際にユーティリティ関数をエクスポートするための基本的な手順を説明します。

関数をエクスポートする基本手順

ユーティリティ関数をエクスポートする際には、2つの方法があります。1つは名前付きエクスポート、もう1つはデフォルトエクスポートです。これらのエクスポート方法を使い分けることで、コードの利用状況に応じた柔軟な構造を持たせることができます。

名前付きエクスポート

名前付きエクスポートは、複数の関数や変数を1つのモジュールからエクスポートする際に使われます。モジュールから複数の項目をエクスポートしたい場合に便利です。

// utils/math.ts
export function getMax(numbers: number[]): number {
  return Math.max(...numbers);
}

export function getMin(numbers: number[]): number {
  return Math.min(...numbers);
}

このように、exportキーワードを使って関数を個別にエクスポートします。エクスポートされた関数は、他のモジュールからインポートして利用可能です。

デフォルトエクスポート

デフォルトエクスポートでは、1つの関数やオブジェクトをメインとしてエクスポートする際に使用します。モジュール全体が1つの主要な機能を提供する場合に有効です。

// utils/arrayUtils.ts
export default function sortArray(arr: number[]): number[] {
  return arr.sort((a, b) => a - b);
}

デフォルトエクスポートは、モジュールから1つだけエクスポートされ、インポートする際には特定の名前を付けることができます。

エクスポートの実践例

以下は、複数のユーティリティ関数をエクスポートする例です。関数を適切にエクスポートすることで、他のモジュールから簡単に利用できるようになります。

// utils/stringUtils.ts
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function toLowerCase(str: string): string {
  return str.toLowerCase();
}

これにより、capitalizeやtoLowerCaseといった関数が他のファイルでも簡単に使えるようになります。次章では、エクスポートした関数を実際にインポートする手順を解説します。

関数をインポートする手順

エクスポートされたユーティリティ関数を他のファイルで利用するためには、importキーワードを使用して関数をインポートします。ESModulesでは、モジュールごとに必要な関数やオブジェクトだけを取り込むことができ、コードの効率や可読性が向上します。このセクションでは、実際に関数をインポートする手順を詳しく解説します。

名前付きエクスポートをインポートする方法

名前付きエクスポートをインポートする場合は、エクスポートされた関数やオブジェクトの名前をそのまま使ってインポートします。以下の例では、複数の関数をインポートする場合と1つの関数だけをインポートする場合の両方を紹介します。

// main.ts
import { getMax, getMin } from './utils/math';

const numbers = [10, 20, 30, 40, 50];
console.log(getMax(numbers)); // 50
console.log(getMin(numbers)); // 10

このように、{}の中に関数名を列挙することで、エクスポートされた関数をまとめてインポートすることができます。また、必要な関数だけをインポートすることも可能です。

// main.ts
import { getMax } from './utils/math';

const numbers = [10, 20, 30];
console.log(getMax(numbers)); // 30

デフォルトエクスポートをインポートする方法

デフォルトエクスポートをインポートする場合は、import文に任意の名前を指定して、その名前で関数を使います。名前付きエクスポートとは異なり、インポート時に必ずしも関数の元の名前を使用する必要はありません。

// main.ts
import sortArray from './utils/arrayUtils';

const numbers = [30, 10, 20];
console.log(sortArray(numbers)); // [10, 20, 30]

デフォルトエクスポートは、モジュールごとに1つだけのエクスポートが許され、インポートする際に独自の名前を指定できます。

名前の変更（エイリアス）の利用

エクスポートされた関数名が他のモジュールや変数名と衝突する場合、インポート時にエイリアスを使用して名前を変更することができます。エイリアスは、特にプロジェクトが大規模化する際に役立ちます。

// main.ts
import { getMax as findMax } from './utils/math';

const numbers = [5, 15, 25];
console.log(findMax(numbers)); // 25

このように、asキーワードを使って関数名を変更することができます。名前を分かりやすく整理することで、コードの可読性が向上します。

まとめてすべてのエクスポートをインポートする方法

モジュール全体を1つのオブジェクトとしてインポートすることも可能です。この方法は、すべての関数や変数を一括で使用したい場合に便利です。

// main.ts
import * as mathUtils from './utils/math';

const numbers = [7, 17, 27];
console.log(mathUtils.getMax(numbers)); // 27
console.log(mathUtils.getMin(numbers)); // 7

この場合、mathUtilsというオブジェクトにすべての関数がまとめられ、ドット演算子を使ってアクセスできます。

次章では、名前付きエクスポートとデフォルトエクスポートの違いや、それらの使い分けについて詳しく説明します。

名前付きエクスポートとデフォルトエクスポートの使い分け

ESModulesでは、関数や変数をエクスポートする際に、名前付きエクスポートとデフォルトエクスポートの2つの方法があります。これらのエクスポート方法にはそれぞれの利点があり、状況に応じて使い分けることが重要です。このセクションでは、両者の違いと、それぞれの適した使い方について詳しく解説します。

名前付きエクスポート

名前付きエクスポートは、複数の関数や変数を同時にエクスポートする際に使用されます。各エクスポートに名前が付けられているため、モジュール内に複数のユーティリティを定義する場合に便利です。

// utils/math.ts
export function getMax(numbers: number[]): number {
  return Math.max(...numbers);
}

export function getMin(numbers: number[]): number {
  return Math.min(...numbers);
}

名前付きエクスポートは、以下のようにインポート時に必要な関数だけを選んで取り込むことができます。

// main.ts
import { getMax } from './utils/math';

const numbers = [1, 2, 3];
console.log(getMax(numbers)); // 3

名前付きエクスポートを使うべき場合

• 複数の関数や変数を同時にエクスポートしたい場合: モジュール内に複数の機能が含まれているとき、必要なものだけをインポートできます。
• 特定の機能に名前が必要な場合: 各エクスポートが固有の名前を持つため、他のモジュールで関数や変数名が衝突することを防げます。

デフォルトエクスポート

デフォルトエクスポートは、モジュールが1つのメイン機能を提供する場合に使われます。モジュール内でエクスポートされる関数や変数が1つだけの場合や、そのモジュールのメイン機能を強調したい場合に適しています。

// utils/arrayUtils.ts
export default function sortArray(arr: number[]): number[] {
  return arr.sort((a, b) => a - b);
}

デフォルトエクスポートをインポートする際には、関数名を自由に付けることができます。

// main.ts
import sort from './utils/arrayUtils';

const numbers = [3, 1, 2];
console.log(sort(numbers)); // [1, 2, 3]

デフォルトエクスポートを使うべき場合

• モジュールが1つの主要な機能を持つ場合: モジュールが特定の目的を持っている場合に、その機能をデフォルトエクスポートとして提供します。
• 関数名を自由に決めたい場合: デフォルトエクスポートは、インポート時に関数名を自由に付けられるため、プロジェクト全体のコード構造に合わせた名前を付けることが可能です。

使い分けの具体例

例えば、mathモジュールには複数のユーティリティ関数があり、個々にインポートして使いたい場合、名前付きエクスポートが最適です。一方、特定の処理を1つだけ提供するモジュールでは、デフォルトエクスポートを使うことで、インポートが簡単になり、コードが読みやすくなります。

// 名前付きエクスポートの例
import { getMax, getMin } from './utils/math';

// デフォルトエクスポートの例
import sortArray from './utils/arrayUtils';

名前付きエクスポートは、モジュールが多機能な場合や、特定の機能だけを選んでインポートしたい場合に適しています。一方、デフォルトエクスポートは、モジュールが単一機能を提供する場合に効果的です。

次章では、ESModulesを使って複数ファイル間で依存関係を管理する方法について詳しく説明します。

ESModulesを使った複数ファイル間での依存管理

プロジェクトが成長するにつれて、複数のファイルやモジュール間で依存関係を適切に管理することが不可欠になります。ESModulesを使用することで、複数のモジュールにまたがる関数や変数を効率的に管理でき、コードの整理が容易になります。この章では、ESModulesを使った依存関係の管理方法と、プロジェクト全体を通じてモジュールをどのように効率的に扱うかについて説明します。

依存関係管理の重要性

複数のファイルに分割されたコードでは、各ファイルが他のファイルから機能を呼び出すことが一般的です。依存関係を明確に管理することで、以下のような利点があります。

コードの再利用性が向上する

特定の機能を1つのモジュールにまとめておけば、他の部分でも何度も使い回すことができ、重複したコードを書く必要がなくなります。

モジュール間の依存関係が明確になる

依存関係がしっかり管理されていると、どのモジュールがどの機能に依存しているかが明確になり、修正や追加の際にも影響範囲を把握しやすくなります。

ESModulesを使った依存関係の管理方法

TypeScriptやJavaScriptのプロジェクトでは、ESModulesを使って他のファイルから関数や変数をインポートすることで依存関係を解決します。依存関係を管理する基本的な方法は、関数や変数をエクスポートし、それを必要な場所でインポートすることです。

例えば、プロジェクト内で複数のユーティリティ関数を定義して、それぞれの関数を特定のモジュールで使用する場合、モジュールごとに適切にインポート・エクスポートを行うことで依存関係が管理されます。

// utils/math.ts
export function getMax(numbers: number[]): number {
  return Math.max(...numbers);
}

export function getMin(numbers: number[]): number {
  return Math.min(...numbers);
}

// main.ts
import { getMax } from './utils/math';

const numbers = [1, 2, 3, 4];
console.log(getMax(numbers)); // 4

依存関係を整理するフォルダ構成の工夫

複数のモジュールが混在するプロジェクトでは、依存関係を管理しやすくするためにフォルダ構成を工夫することも重要です。例えば、ユーティリティ関数をまとめたutilsフォルダを作成し、すべての汎用的な関数をそこに集約することで、整理された依存関係管理が可能になります。

src/
├── utils/
│   ├── math.ts
│   ├── string.ts
├── components/
│   ├── header.ts
│   ├── footer.ts
├── main.ts

このように、各モジュールが特定の役割を持つように整理することで、依存関係が分かりやすくなり、修正や追加が容易になります。

循環依存の回避

複数のモジュール間で依存関係が複雑になると、循環依存と呼ばれる問題が発生することがあります。循環依存とは、AモジュールがBモジュールに依存し、さらにBモジュールがAモジュールに依存する状況のことです。このような状況を避けるためには、モジュールの責務を明確に分け、共通の依存関係は分離されたモジュールにまとめるなどの工夫が必要です。

// a.ts
import { fromB } from './b';
export const fromA = 'A';

// b.ts
import { fromA } from './a';  // 循環依存の可能性
export const fromB = 'B';

循環依存は、依存関係が大きくなると見落としやすい問題ですが、モジュールの役割分担を意識することで回避できます。

ツールを利用した依存関係の管理

WebpackやRollupといったバンドラーツールを使用することで、依存関係を自動的に解決し、パフォーマンスを向上させることができます。これらのツールは、依存関係を解析し、必要なモジュールだけをまとめて最適化してくれます。また、ツールを使用することで、依存関係の可視化や管理が容易になり、バグの発生を抑制することができます。

次章では、ESModulesと従来のCommonJSの違いについて比較し、ESModulesの利点について詳しく説明します。

CommonJSとの違い

JavaScriptのモジュールシステムには、ESModules（ECMAScript Modules）と従来のCommonJSがあります。どちらもモジュールを分割し、コードの再利用性を高めるために使用されますが、それぞれに特徴的な違いがあります。この章では、ESModulesとCommonJSの主な違いを説明し、それぞれの利点を比較します。

ESModulesとCommonJSの基本的な違い

ESModulesは、ECMAScriptの標準として採用され、ブラウザとNode.jsの両方でサポートされています。一方、CommonJSは、Node.jsで使用される伝統的なモジュールシステムです。これらのモジュールシステムは、エクスポート・インポートの仕組みやモジュールの読み込みタイミングなど、いくつかの点で異なります。

1. モジュールのエクスポート方法

• CommonJSでは、module.exportsまたはexportsオブジェクトを使用して、モジュールをエクスポートします。以下はCommonJSのエクスポート例です。

// CommonJS (Node.js)
module.exports = function sum(a, b) {
  return a + b;
};

• ESModulesでは、exportまたはexport defaultを使用して、モジュールをエクスポートします。

// ESModules
export function sum(a: number, b: number): number {
  return a + b;
}

2. モジュールのインポート方法

• CommonJSでは、require()関数を使ってモジュールをインポートします。

// CommonJS
const sum = require('./sum');
console.log(sum(2, 3)); // 5

• ESModulesでは、importキーワードを使用します。

// ESModules
import { sum } from './sum';
console.log(sum(2, 3)); // 5

3. モジュールの読み込みタイミング

• CommonJSは、モジュールの読み込みが同期的に行われます。require()が実行されると、その時点でモジュールが読み込まれます。これにより、Node.jsのサーバーサイド環境で簡単に使える反面、大量のモジュールを読み込むと起動時間が遅くなる可能性があります。
• ESModulesは、モジュールが非同期的に読み込まれます。これは、ブラウザ環境などで効率的にファイルをロードできるように設計されており、ネットワークの待ち時間を減らすために役立ちます。

4. 静的解析の有無

• CommonJSは動的なモジュールシステムであり、モジュールの依存関係がコード実行時に決定されます。
• ESModulesは静的なモジュールシステムです。これにより、コードが実行される前に依存関係が解析されるため、ツールによる最適化が可能です。静的解析のおかげで、ビルド時に依存関係のエラーを早期に発見でき、パフォーマンスも向上します。

ESModulesの利点

1. ブラウザサポート

ESModulesは、モダンブラウザでネイティブにサポートされています。<script type="module">を使用することで、直接ブラウザでモジュールを読み込むことができるため、フロントエンド開発に適しています。

2. 静的解析による最適化

静的解析により、ビルドツール（WebpackやRollupなど）は、不要なコードを除去するツリ―シェイキングを行うことができます。これにより、プロダクション向けのコードサイズを減らし、パフォーマンスが向上します。

3. デフォルトエクスポートと名前付きエクスポートの柔軟性

ESModulesでは、デフォルトエクスポートと名前付きエクスポートの両方をサポートしており、モジュールを使う側が柔軟にインポート方法を選べます。これにより、特定のモジュールが1つの主要機能を提供する場合や、複数の機能を同時に提供する場合にも対応できます。

CommonJSの利点

1. 広範なNode.jsサポート

CommonJSは、Node.jsの標準モジュールシステムとして長い歴史があり、豊富なライブラリとツールチェーンが存在します。既存のNode.jsプロジェクトとの互換性が求められる場合、CommonJSは便利です。

2. シンプルな構文

CommonJSのrequire()とmodule.exportsは、シンプルで直感的なため、サーバーサイドの開発では使い勝手が良いとされています。

使い分けの指針

• フロントエンド開発やモダンブラウザ向けのコード: ESModulesを推奨します。ブラウザサポートが豊富で、モジュールの静的解析によるパフォーマンス向上が期待できます。
• Node.jsでのサーバーサイド開発: 既存のプロジェクトやライブラリとの互換性を重視する場合は、CommonJSが依然として有効です。ただし、Node.jsもESModulesをサポートしているため、モダンな開発環境ではESModulesに移行することが推奨されています。

次章では、実際にESModulesを使ったユーティリティ関数の分割と管理の実践例について解説します。

実践例：ユーティリティ関数の分割と管理

ユーティリティ関数を効果的に管理するために、プロジェクトをモジュールごとに整理し、それぞれのモジュールで関数を適切にエクスポート・インポートすることが重要です。ここでは、具体的なプロジェクト例を通じて、ESModulesを使ったユーティリティ関数の分割と管理の方法を説明します。

ユーティリティ関数を複数ファイルに分割

プロジェクトが成長するにつれて、ユーティリティ関数も増えていきます。これを効率的に管理するために、関数を論理的なグループに分割し、それぞれの機能に応じたファイルにまとめます。例えば、数値操作に関する関数、文字列操作に関する関数、配列操作に関する関数をそれぞれ別々のファイルに定義します。

src/
├── utils/
│   ├── math.ts       // 数値関連のユーティリティ
│   ├── string.ts     // 文字列関連のユーティリティ
│   ├── array.ts      // 配列関連のユーティリティ
├── main.ts           // メインエントリーポイント

この構成により、各ファイルは明確な責任を持ち、コードの可読性とメンテナンス性が向上します。

実際のユーティリティ関数の定義

それぞれのファイルに、特定のユーティリティ関数を定義し、必要に応じてエクスポートします。以下は、math.tsファイルに数値関連のユーティリティ関数を定義する例です。

// utils/math.ts
export function getMax(numbers: number[]): number {
  return Math.max(...numbers);
}

export function getMin(numbers: number[]): number {
  return Math.min(...numbers);
}

次に、string.tsには文字列関連の関数を定義します。

// utils/string.ts
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function toLowerCase(str: string): string {
  return str.toLowerCase();
}

配列関連の関数は、array.tsに分割します。

// utils/array.ts
export function sortArray(arr: number[]): number[] {
  return arr.sort((a, b) => a - b);
}

export function shuffleArray(arr: number[]): number[] {
  return arr.sort(() => Math.random() - 0.5);
}

ユーティリティ関数をインポートして利用する

これらのユーティリティ関数を、main.tsのメインファイルでインポートし、使用します。モジュールごとに必要な関数だけをインポートできるため、コードの効率化が図れます。

// main.ts
import { getMax, getMin } from './utils/math';
import { capitalize } from './utils/string';
import { sortArray } from './utils/array';

const numbers = [10, 20, 30, 40, 50];
console.log(getMax(numbers)); // 50
console.log(getMin(numbers)); // 10

const text = "hello world";
console.log(capitalize(text)); // Hello world

const unsortedArray = [3, 1, 4, 1, 5];
console.log(sortArray(unsortedArray)); // [1, 1, 3, 4, 5]

このように、各モジュールから必要な関数だけを選んでインポートすることで、モジュール同士の依存関係が明確になり、不要なコードを避けることができます。

再利用性とモジュールの拡張性

プロジェクトが大きくなると、新しいユーティリティ関数を追加する必要が生じますが、この構造を使えば、新しい機能を追加しても他の部分に影響を与えることなく、既存のファイルに関数を追加するか、必要に応じて新しいモジュールを作成して管理できます。

例えば、新しい関数をmath.tsに追加する場合、次のように簡単に拡張できます。

// utils/math.ts
export function sum(numbers: number[]): number {
  return numbers.reduce((acc, val) => acc + val, 0);
}

このように、モジュール化された構造を使用することで、新しい機能を追加する際もシンプルで直感的な運用が可能になります。

まとめ

ESModulesを使用してユーティリティ関数を分割・管理することで、コードの再利用性とメンテナンス性を向上させることができます。関数ごとに責任を明確に分けることで、依存関係が整理され、プロジェクト全体の可読性が向上します。さらに、モジュールを増やしてもコード全体がシンプルであり、機能追加や修正も容易に行えるようになります。

次章では、エクスポートやインポート時に発生しやすいエラーとその対策について詳しく説明します。

よくあるエラーとその対策

ESModulesを使用してユーティリティ関数をエクスポート・インポートする際、初心者が直面することが多いエラーがあります。これらのエラーはモジュールの使い方や設定に起因するもので、適切な対策を講じることで容易に解決できます。この章では、よくあるエラーとその原因、さらにそれぞれの対策について詳しく解説します。

エラー1: “Cannot use import statement outside a module”

原因

このエラーは、import文を使用しているのに、環境やプロジェクトがESModulesとして正しく設定されていない場合に発生します。主に以下のケースが考えられます：

• tsconfig.jsonで module オプションが正しく設定されていない
• JavaScriptでモジュールを使用しているが、HTMLファイルで <script> タグに type="module" が設定されていない

対策

1. TypeScriptの設定確認: tsconfig.jsonで module を esnext または ES2020 に設定します。

   {
     "compilerOptions": {
       "module": "esnext",
       "target": "es6"
     }
   }

2. ブラウザでの設定確認: HTMLファイルでモジュールを利用する際は、<script> タグに type="module" を追加する必要があります。

   <script type="module" src="main.js"></script>

エラー2: “Unexpected token ‘export'”

原因

このエラーは、Node.jsでESModulesを利用している場合によく見られます。デフォルトのNode.jsでは、requireを使用するCommonJSがサポートされており、exportやimportが使えないことが原因です。

対策

Node.jsでESModulesを使用するには、package.jsonで以下の設定を行い、Node.jsにESModulesを使用することを明示します。

{
  "type": "module"
}

また、ファイルの拡張子を .js ではなく .mjs に変更することでもESModulesを使うことができます。

エラー3: “Module not found” または “Cannot find module”

原因

このエラーは、モジュールのパスが正しく指定されていない場合に発生します。相対パスの指定ミスや、モジュール名のタイプミスが原因として考えられます。また、ファイル拡張子を省略すると、環境によってはファイルが見つからないことがあります。

対策

1. 正しいパスを確認: インポート時には、相対パスをしっかり確認することが重要です。例えば、モジュールが1階層上にある場合は ../ を使います。

   import { getMax } from '../utils/math';

2. 拡張子を明示する: JavaScriptファイルの場合、ファイルの拡張子 .js を省略しないほうが良いことがあります。これは、環境によって拡張子が必要な場合があるためです。

   import { getMax } from './utils/math.js';

エラー4: “Cannot reassign import” または “Assignment to constant variable”

原因

このエラーは、インポートしたモジュールや関数を再代入しようとした場合に発生します。importされた変数や関数は読み取り専用（immutable）であり、再代入は許可されていません。

対策

インポートした関数や変数をそのまま使用し、再代入や変更を避けるようにします。例えば、次のようなコードはエラーになります。

import { getMax } from './utils/math';

getMax = function() {
  return 0;
}; // エラー

このようなコードは再代入せず、元の関数をそのまま使用するか、別の変数名を使って新しい関数を定義してください。

エラー5: 循環依存（Circular Dependency）

原因

循環依存は、2つ以上のモジュールが互いに依存している場合に発生します。例えば、AモジュールがBモジュールに依存し、BモジュールがAモジュールに依存している場合に、無限ループが発生することがあります。

対策

循環依存を避けるためには、依存関係を整理し、どのモジュールがどこに依存しているかを明確にする必要があります。共通の機能は別のモジュールに切り出すことで、依存関係の循環を防ぐことができます。

// 解決策として、共通の機能を別のモジュールに分離する
import { sharedFunction } from './sharedUtils';

まとめ

ESModulesを使用した際によく発生するエラーは、設定やパスの問題、モジュールの使い方に起因するものが多いです。これらのエラーを回避するためには、TypeScriptやJavaScriptの設定を適切に管理し、モジュールの依存関係を整理することが重要です。問題が発生した場合は、エラーメッセージを元に根本的な原因を突き止め、適切に対策を講じましょう。

次章では、本記事で紹介した内容を簡潔にまとめ、ユーティリティ関数の共有方法のポイントを振り返ります。

まとめ

本記事では、TypeScriptでESModulesを使用してユーティリティ関数を効率的に共有する方法について解説しました。ESModulesの基本概念から、関数のエクスポートとインポートの具体的な手順、名前付きエクスポートとデフォルトエクスポートの違い、さらに複数ファイル間での依存関係管理の方法まで、詳細に説明しました。また、よくあるエラーとその対策も紹介し、モジュール利用の際に注意すべきポイントを整理しました。

ESModulesを活用することで、コードの再利用性やメンテナンス性が向上し、プロジェクトの規模が拡大しても効率的な管理が可能になります。