TypeScriptでimport文に出るTS2306エラーの直し方
error TS2306: File '…/utils.ts' is not a module. は、import した先のファイルに import も export もないときに出ます。TypeScript はそのファイルをモジュールではなく「スクリプト」として扱うため、そこから何かを import できません。使いたい関数や型の宣言に export を付けると消えます。
関数や型を別ファイルに分けて書き、import { add } from "./utils"; のように読み込んだら、tsc の型チェックや VS Code などのエディターで「is not a module」と出たときは、この記事の手順で直せます。私は検証環境でこのエラーを起こし、メッセージをそのまま載せました。直したあとにエラーが消えることも、tsc とエディター向けの言語サーバーの両方で確かめています。
検証環境は Ubuntu 24.04、Node.js 22.23.4、npm 10.9.9、TypeScript 7.0.2 です。エディターの表示は、VS Code などのエディター本体ではなく、TypeScript 7 の言語サーバー(tsc --lsp --stdio)を直接動かして確かめています。VS Code の画面での見え方、TypeScript 7 より前のバージョン、.js ファイルを allowJs で読み込む場合は試していません。
export のないファイルを import してエラーを起こす
空のフォルダーで npm init -y を実行し、TypeScript 7.0.2 を入れました。tsconfig.json は次の内容です。
{
"compilerOptions": {
"module": "esnext",
"moduleResolution": "bundler",
"target": "es2022",
"strict": true,
"noEmit": true
},
"include": ["src"]
}
src/utils.ts に足し算の関数を書き、export は付けずにおきます。
// src/utils.ts
function add(a: number, b: number): number {
return a + b;
}
src/main.ts から、この関数を import します。
// src/main.ts
import { add } from "./utils";
console.log(add(1, 2));
npx tsc を実行すると、次のエラーが出て、終了コードは 1 でした。メッセージの中のパスは、検証環境の作業フォルダーを /path/to/app に置き換えています。
$ npx tsc
src/main.ts(1,21): error TS2306: File '/path/to/app/src/utils.ts' is not a module.
--pretty を付けると、エラーの場所が "./utils" の部分だと分かります(色は省いています)。
src/main.ts:1:21 - error TS2306: File '/path/to/app/src/utils.ts' is not a module.
1 import { add } from "./utils";
~~~~~~~~~
Found 1 error in src/main.ts:1
エラーが出るのは、import を書いた src/main.ts のほうです。メッセージに出ているのは、読み込まれる側の src/utils.ts のパスです。直すのは、このパスのファイルです。
言語サーバーに src/main.ts を開かせたときも、同じ内容の診断が1件返りました。下の表示は、私が書いた小さなスクリプトで、言語サーバーの応答を1件1行に整え、行と列を1から数えるように直したものです(パスは同じく置き換えています)。1:21-1:30 は、1行目の "./utils" の範囲です。
diagnostics (1):
1:21-1:30 severity=1 source=ts code=2306 File '/path/to/app/src/utils.ts' is not a module.
import utils from "./utils"; や import * as utils from "./utils"; のように書き方を変えても、同じ TS2306 が出ました。一方、import "./utils"; のように、何も取り出さずにファイルを読み込むだけの書き方では、エラーは出ませんでした。
import も export もないファイルはモジュールにならない
TypeScript ハンドブックのモジュールの章には、トップレベルに import か export があるファイルはモジュールとして扱われ、どちらもないファイルは、中身がグローバルスコープで見えるスクリプトとして扱われる、とあります。
src/utils.ts には import も export もないので、スクリプトです。スクリプトは何も export しないため、import { add } from "./utils" で取り出せるものがありません。TS2306 は、この「モジュールでないファイルから import しようとしている」ことを知らせています。
直し方:使いたい関数に export を付ける
src/utils.ts の関数の前に export を付けます。
// src/utils.ts
export function add(a: number, b: number): number {
return a + b;
}
npx tsc は何も出力せずに終了コード 0 になりました。言語サーバーの診断も 0 件です。export があることで src/utils.ts はモジュールになり、add を import できるようになりました。
export {} を足すだけでは、別のエラーに変わる
ハンドブックには、import も export もないファイルをモジュールとして扱いたいときは export {}; の1行を足す、という案内があります。ただ、これは「何も export しないモジュール」にするための書き方です。
src/utils.ts の末尾に export {}; だけを足し、add には export を付けずに試しました。
// src/utils.ts
function add(a: number, b: number): number {
return a + b;
}
export {};
TS2306 は消えましたが、代わりに TS2459 が出ました。「./utils は add をファイルの中で宣言しているが、export していない」という意味です。
$ npx tsc
src/main.ts(1,10): error TS2459: Module '"./utils"' declares 'add' locally, but it is not exported.
別のファイルから使う関数なら、結局は add そのものに export を付ける必要があります。
tsc –init で作ったプロジェクトでは、同じコードで TS2459 が出る
npx tsc --init で作った tsconfig.json では、同じコードでも TS2306 ではなく TS2459 が出ました。TypeScript 7.0.2 の tsc --init が作る tsconfig.json には、次の2行が入っていました。
$ npx tsc --init > /dev/null && grep -n -E "\"module\"|moduleDetection" tsconfig.json
10: "module": "nodenext",
41: "moduleDetection": "force",
src/main.ts は、拡張子を付けて import { add } from "./utils.js"; と書きました。src/utils.ts は export のない最初のものです。
$ npx tsc --noEmit
src/main.ts(1,10): error TS2459: Module '"./utils.js"' declares 'add' locally, but it is not exported.
moduleDetection の説明によると、"force" は宣言ファイル(.d.ts)以外のすべてのファイルをモジュールとして扱う設定です。src/utils.ts は「何も export していないモジュール」になるので、メッセージが TS2459 に変わります。同じプロジェクトで --moduleDetection auto を付けて実行すると、TS2306 に戻りました(package.json に "type" がない状態です)。
$ npx tsc --noEmit --moduleDetection auto
src/main.ts(1,21): error TS2306: File '/path/to/app-node/src/utils.ts' is not a module.
記事の最初に作った、module が esnext のプロジェクトで --moduleDetection force を付けた場合も、TS2459 でした。どちらのメッセージでも、直し方は add に export を付けることです。ただ、tsc --init で作ったプロジェクトでは、export を付けただけでは終わりませんでした。package.json に "type" がないまま add に export を付けると、次の2件のエラーが出ました。
$ npx tsc --noEmit
src/main.ts(1,10): error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. Adjust the 'type' field in the nearest 'package.json' to make this file an ECMAScript module, or adjust your 'verbatimModuleSyntax', 'module', and 'moduleResolution' settings in TypeScript.
src/utils.ts(1,1): error TS1287: A top-level 'export' modifier cannot be used on value declarations in a CommonJS module when 'verbatimModuleSyntax' is enabled.
この tsconfig.json には "verbatimModuleSyntax": true も入っていました。package.json に "type" がないとファイルは CommonJS として扱われ、verbatimModuleSyntax が有効なので、そのファイルには import や export をそのまま書けない、というエラーです。メッセージの案内どおり、npm pkg set type=module で package.json に "type": "module" を足すと、npx tsc --noEmit は終了コード 0 になりました。
.d.ts に書いた型を import したときも出る
型だけを書いた宣言ファイルでも、同じことが起きます。src/types.d.ts に、export を付けずに型を書きました。
// src/types.d.ts
interface User {
id: number;
name: string;
}
これを src/profile.ts から import します。
// src/profile.ts
import { User } from "./types";
const user: User = { id: 1, name: "neko" };
console.log(user);
$ npx tsc
src/profile.ts(1,22): error TS2306: File '/path/to/app/src/types.d.ts' is not a module.
宣言ファイルは moduleDetection の "force" の対象外なので、--moduleDetection force を付けても同じ TS2306 が出ました。直し方は2つあり、どちらも npx tsc が終了コード 0 になりました。
1つ目は、src/types.d.ts の interface に export を付けて、import して使う方法です。
// src/types.d.ts
export interface User {
id: number;
name: string;
}
2つ目は、src/types.d.ts は export なしのままにして、src/profile.ts の import の行を消す方法です。export のない宣言ファイルの型はグローバルスコープにあるので、import しなくても User を使えます。
// src/profile.ts
const user: User = { id: 1, name: "neko" };
console.log(user);
2つの直し方を混ぜないようにします。src/types.d.ts に export を付けると、User はグローバルの型ではなくなります。import せずに User を使っているファイルがあると、そちらに error TS2304: Cannot find name 'User'. が出ました。どこかのファイルが import なしで使っている型に export を付けるときは、そのファイルにも import を足します。





