✨

TypeScript + モダンパッケージで発生する import 解決エラー、tsconfig の設定を見直そう

2025/04/22に公開

 はじめに最近、Shopifyの公式SDKである @shopify/shopify-api を最新バージョンに上げたところ、正常に使えていたimportが突然モジュールが見つからないエラーに遭遇しました。
エラーの内容は以下のようなものでした：
モジュール '@shopify/shopify-api/rest/admin/2025-04' またはそれに対応する型宣言が見つかりません。
こちらについてどう対処すればよいのか？について今回記載していきます。

 結論：tsconfig設定のmoduleResolutionが古いままだったエラーの主な原因は、tsconfig.jsonのmoduleResolutionの値が"node"のままだったことです。
Shopifyのような最新SDKでは、Node.jsのESM対応の一環として、package.jsonに以下のような "exports" フィールドが定義されています。
{
  "exports": {
    "./rest/admin/*": {
      "types": "./dist/ts/rest/admin/*/index.d.ts",
      "import": "./dist/esm/rest/admin/*/index.mjs",
      "require": "./dist/cjs/rest/admin/*/index.js"
    }
  }
}
この構造により、モジュールの外部からアクセスできるパスが厳密に制御されるようになりました。
しかし、TypeScriptのmoduleResolutionが"node"のままだと、これらの制限を解釈できず、以下のような「モジュールが見つからない」エラーが発生してしまいます。

 解決策：tsconfig.json の設定を修正moduleResolutionとmoduleを合わせて修正しておきます。
{
  "compilerOptions": {
-   "module": "ESNext",
-   "moduleResolution": "node",
+   "module": "NodeNext",
+   "moduleResolution": "NodeNext",
    ...
  }
}

 公式情報情報📘 TypeScript Handbook: moduleResolution

 さいごにパッケージのバージョンアップ時に起こる不可解なimportエラーは、Node.jsやTypeScriptの場ジョンアップに伴う、追加の設定変更が必要でした。

（エディタ上ではimportできない旨の記載しかないので、tsconfigを理解できていないと解消方法が見つけづらいです。）
今後もモダンなSDKを使う場合には、tsconfig.jsonの設定を見直すことがトラブル回避できると思うので、プロジェクト開始時はしっかり設定しておこうと思います。
同じようなエラーに遭遇した方の助けになれば幸いです 🙌

はじめに

結論：tsconfig設定のmoduleResolutionが古いままだった

解決策：tsconfig.json の設定を修正

公式情報情報

さいごに

Discussion