TypeScriptでJSONをインポートする：resolveJsonModuleの設定とESM環境での活用法

2026年5月9日

モジュール・型定義ファイル

TypeScriptを用いたモダンなフロントエンドやサーバーサイドの開発において、外部のJSONファイルを直接インポートして利用したい場面は非常に多く存在します。

設定ファイルや静的なマスタデータ、ローカライゼーション用のテキストデータなど、JSON形式はデータの受け渡しにおいて標準的な地位を確立しています。

しかし、TypeScriptでJSONファイルを安全かつ効率的に扱うためには、コンパイラオプションの適切な理解と設定が欠かせません。

本記事では、resolveJsonModuleの基本的な役割から、2026年現在の主流であるESM（ECMAScript Modules）環境における最新のインポート手法までを詳しく解説します。

目次 [ close ]

resolveJsonModuleとは何か

resolveJsonModuleは、TypeScriptコンパイラに対してJSONファイルをモジュールとして読み込むことを許可するための設定オプションです。

通常、TypeScriptは .ts や .tsx といった拡張子のファイルをモジュールとして認識しますが、このオプションを有効にすることで .json 拡張子もその対象に含まれます。

この機能の最大のメリットは、インポートしたJSONデータに対してTypeScriptが自動的に型推論を行ってくれる点にあります。

開発者は手動でインターフェースや型定義を作成することなく、JSONの構造に基づいた型安全なプログラミングが可能になります。

tsconfig.jsonでの設定方法

resolveJsonModuleを利用するには、プロジェクトのルートディレクトリにある tsconfig.json ファイルを編集する必要があります。

compilerOptions の中に "resolveJsonModule": true を追加することで、プロジェクト全体でJSONのインポートが可能になります。

多くの場合、この設定と合わせて moduleResolution を "node" や "bundler" に設定することが推奨されます。

JSON

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true
  }
}

esModuleInteropとの関係性

JSONファイルを import 文で読み込む際、多くの場合で esModuleInterop オプションも同時に有効にする必要があります。

JSONファイルはデフォルトで「Default Export（デフォルトエクスポート）」の形式として扱われるためです。

esModuleInterop が false のままだと、import data from "./data.json" という記述がコンパイルエラーになることがあります。

モダンなTypeScriptプロジェクトでは、これら2つのオプションをセットで true にしておくのが標準的な作法となっています。

JSONインポートの基本実装

設定が完了したら、実際にTypeScriptコード内でJSONファイルをインポートしてみましょう。

ここでは、以下のような config.json というファイルが存在すると仮定します。

JSON

{
  "apiEndpoint": "https://api.example.com",
  "timeout": 5000,
  "features": {
    "darkMode": true,
    "betaAccess": false
  }
}

このJSONファイルをTypeScript側で読み込むコードは、以下のようになります。

TypeScript

// JSONファイルをインポート
import config from "./config.json";

// 型推論が効いているため、プロパティに安全にアクセス可能
console.log(config.apiEndpoint);
console.log(config.features.darkMode);

// 存在しないプロパティにアクセスしようとするとコンパイルエラーになります
// console.log(config.unknownProperty);

実行結果

https://api.example.com
true

このように、インポートした config オブジェクトには、JSONのキーに基づいた型が自動的に付与されます。

VS Codeなどのエディタを使用している場合、config. と入力した時点でプロパティ名が補完されるため、開発効率が劇的に向上します。

ESM環境における最新のJSONインポート

2026年現在のTypeScript開発において避けて通れないのが、Node.jsやブラウザにおけるネイティブESM（ECMAScript Modules）への対応です。

従来のCommonJS環境とは異なり、ESM環境でJSONをインポートする際には「Import Attributes（以前のImport Assertions）」という構文が必要になる場合があります。

これは、JavaScriptの実行環境がセキュリティ上の理由から、インポートされるファイルの形式を明示的に指定することを求めているためです。

Import Attributesの構文

最新のTypeScriptおよびNode.js環境では、以下のような with 構文を使用してJSONを読み込みます。

TypeScript

// Import Attributesを使用したJSONのインポート
import data from "./data.json" with { type: "json" };

console.log(data.version);

この with { type: "json" } という記述がない場合、実行環境によっては「モジュールとして解析できない」といったエラーが発生する可能性があります。

TypeScriptはこの構文を正しく解釈し、従来通り resolveJsonModule と組み合わせて型推論を提供します。

tsconfig.jsonのmodule設定の影響

tsconfig.json の module 設定が NodeNext や Node16 に指定されている場合、TypeScriptはより厳格なチェックを行います。

このモードでは、ファイル拡張子を省略せずに記述することや、前述の with 構文の使用が必須となるケースが増えます。

プロジェクトのターゲット環境がNode.jsの最新版である場合は、これらの新しい構文に準拠することが求められます。

実務での活用シーンとメリット

resolveJsonModule を活用する場面は多岐にわたりますが、特に有効な3つのユースケースを紹介します。

1. プロジェクト情報の取得

package.json を直接インポートすることで、アプリケーション内で自身のバージョン番号や依存ライブラリの情報を利用できます。

TypeScript

import pkg from "../package.json";

export const getAppVersion = () => {
  return pkg.version;
};

これにより、手動でバージョン文字列を定義する手間が省け、情報の不整合を防ぐことができます。

2. 国際化（i18n）対応

多言語対応のプロジェクトでは、各言語の翻訳テキストをJSONファイルで管理するのが一般的です。

TypeScriptでこれらをインポートすれば、翻訳キーが存在するかどうかをコンパイル時にチェックできるようになります。

「翻訳漏れ」によるランタイムエラーを未然に防げるのは、大規模開発において非常に大きなメリットです。

3. モックデータの管理

ユニットテストや開発時のスタブ用として、大量のJSONデータを扱うことがあります。

resolveJsonModule を使用すれば、テストコード内でモックデータを型安全に扱うことができ、APIのレスポンス構造に変更があった際も即座にエラーとして検知可能です。

注意点とトラブルシューティング

非常に便利な機能ですが、利用にあたって注意すべき点もいくつか存在します。

巨大なJSONファイルによるメモリ消費

TypeScriptはインポートしたJSONの全構造をスキャンして型を生成します。

数メガバイトを超えるような極端に巨大なJSONファイルをインポートすると、コンパイル速度が著しく低下したり、エディタが重くなったりすることがあります。

そのような場合は、JSONを分割するか、実行時に fetch や fs.readFile で動的に読み込むことを検討してください。

出力先ディレクトリの構造

TypeScriptをビルドしてJavaScriptを出力する際、JSONファイルも出力先ディレクトリ（distやbuildなど）にコピーされる必要があります。

しかし、TypeScriptコンパイラ自体はJSONファイルを「コピー」する機能を持っていません。

resolveJsonModule を有効にすると、インポートされたJSONは生成されるJSファイル内にインライン展開されるのではなく、参照として残ります。

そのため、webpackやViteといったビルドツール、あるいは cp コマンドなどを使って、JSONファイルを適切に出力先に配置する設定が必要です。

インポートパスの解決エラー

もしJSONファイルをインポートしようとして「Cannot find module」というエラーが出る場合は、以下の項目を確認してください。

確認項目	対応方法
resolveJsonModule の設定	tsconfig.json で true になっているか確認する。
拡張子の有無	import 文で .json を含めているか確認する。
rootDir の範囲	JSONファイルが TypeScript のコンパイル対象に含まれているか確認する。
moduleResolution	“node” や “bundler” など、Node形式の解決が有効になっているか確認する。