できない.dev

TypeScript で NodeNext の import に .js を付けないと解決されない

NodeNext で相対 import が解決されないときは、元が .ts でも .js 拡張子を書けば直る。
ESM 仕様どおりの挙動で、バンドラ前提なら moduleResolution を bundler にするのが楽だ。

公開: 更新:

症状できない · exit 2
npx tsc
src/main.ts(2,21): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './foo.js'?
解決後できた · exit 0
npx tsc

2026-10-24 に node:20(TypeScript 5.9.3 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext' というエラーは、TypeScript が ESM 仕様準拠の挙動にそのまま追従しているために出る。
import './foo' を import './foo.js' に書き換えれば解決する。
違和感があるが、これが正しい。

実行例

node:20(Node.js v20.20.2・TypeScript 5.9.3)環境で上記の手順を動かすと、拡張子なしの import に対して TS2835 エラーが出て、終了コード 2 で終わった。
.js 拡張子を付けると、終了コードは 0 に変わった。

Version 5.9.3
$ npx tsc
src/main.ts(2,21): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './foo.js'?
$ echo $?
2
$ npx tsc
$ echo $?
0

— 2026-10-24 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-24 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • TypeScript 5.9.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 相対 import に .js を付ける

// 修正前
import { foo } from "./foo";
import { bar } from "../utils/bar";
 
// 修正後
import { foo } from "./foo.js";
import { bar } from "../utils/bar.js";

元ファイルが .ts でも、import パスには .js を書く。
TypeScript はコンパイル後のパスとしてこれを解釈する。
違和感があるが、Node.js の ESM 仕様が拡張子必須なのでそれに従う形になっている。
詳しい仕様は TypeScript Modules Reference 公式ドキュメント(新しいタブで開く) にまとまっている。

2. バンドラ前提なら bundler に切り替える

Next.js / Vite / esbuild などバンドラがパス解決を担うプロジェクトでは:

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}

bundler は拡張子を要求しない。
フロントエンド寄りのプロジェクトには、こちらの方が合っている。
各値の選び方は tsconfig moduleResolution 公式(新しいタブで開く) にまとまっている。

3. 検証専用なら .ts 拡張子を許す

noEmit: true で型検査のみのプロジェクトでは:

{
  "compilerOptions": {
    "module": "node16",
    "moduleResolution": "node16",
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}

これで import "./foo.ts" のように .ts 拡張子を書けるようになる。
ただし noEmit 必須なので、ビルド成果物を出すプロジェクトでは使えない。

4. 既存コードの一括変換

VS Code の正規表現置換、または ts-add-js-extension のようなツールで from "./foo" → from "./foo.js" の一括変換ができる。
ファイル数が多いプロジェクトを移行するときに役立つ。

よくある原因

  1. tsconfig.json で "moduleResolution": "node16" または "nodenext" にしている。
  2. package.json の "type": "module" で完全 ESM プロジェクトになっている。
  3. 旧来の moduleResolution: node の慣れで、拡張子なしの import を多用している。
  4. パスエイリアス(@/foo)には警告が出ないので、相対 import だけ直し漏れている。