TypeScriptでTS1208エラーが出たときの直し方

​​TypeScript​トラブルシュート

error TS1208: ... cannot be compiled under '--isolatedModules' because it is considered a global script file. は、tsconfig.json で isolatedModules を有効にしたプロジェクトに、import も export もない .ts ファイルがあると出ます。そのファイルをモジュールとして扱わせれば消えます。やり方は、ファイルに export {}; を書くか、tsconfig.json の moduleDetection を "force" にするかの2つです。

Vite は、型情報を使わずに1ファイルずつ変換するため、isolatedModules を true にするようドキュメントで案内しています。そうしたプロジェクトで tsc の型チェックを実行して、このエラーが出たときの直し方です。

なお、私が試した TypeScript 5.0.2、5.9.3、7.0.2 では、同じファイルでもこのエラーは出ませんでした。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、npm 10.9.9 です。TS1208 は TypeScript 4.9.5 で起こしました。確かめたのは tsc の出力だけです。VS Code などのエディターでの表示、4.9.5 より前のバージョン、Vite などのビルドツールでのビルドは試していません。

import も export もないファイルでエラーを起こす

空のフォルダーで npm init -y を実行し、TypeScript 4.9.5 を入れました。tsconfig.json は次の内容です。isolatedModules を true にし、型チェックだけをするために noEmit も付けています。

json
{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["src"]
}

src/main.ts には、import も export もない2行だけを書きました。

ts
const message: string = "hello";
console.log(message);

npx tsc を実行すると、次のエラーが出て、終了コードは 2 でした。

console
$ npx tsc
src/main.ts(1,1): error TS1208: 'main.ts' cannot be compiled under '--isolatedModules' because it is considered a global script file. Add an import, export, or an empty 'export {}' statement to make it a module.

メッセージは「main.ts はグローバルなスクリプトファイルとみなされるため、--isolatedModules のもとではコンパイルできません。import か export、または空の export {} 文を足してモジュールにしてください」という意味です。--pretty を付けた出力は次のとおりです(色は省いています)。

text
src/main.ts:1:1 - error TS1208: 'main.ts' cannot be compiled under '--isolatedModules' because it is considered a global script file. Add an import, export, or an empty 'export {}' statement to make it a module.

1 const message: string = "hello";
  ~~~~~


Found 1 error in src/main.ts:1

エラーの位置は1行1列目で、--pretty でも最初の語の下に ~ が付くだけです。特定の行の書き方ではなく、ファイルに import も export もないことに対して出ています。

空のファイルや、型だけのファイルでも出る

同じプロジェクトに、次の3つの .ts ファイルと、1つの .d.ts ファイルを足しました。

  • src/empty.ts:中身が空(0バイト)
  • src/comment.ts:// import { format } from "./format"; の1行だけ(import をコメントアウトしたもの)
  • src/types.ts:interface User { name: string; } だけ
  • src/global.d.ts:declare const APP_VERSION: string; だけ

npx tsc を実行すると、.ts ファイルにはすべて TS1208 が出ました。

console
$ npx tsc
src/comment.ts(1,1): error TS1208: 'comment.ts' cannot be compiled under '--isolatedModules' because it is considered a global script file. Add an import, export, or an empty 'export {}' statement to make it a module.
src/empty.ts(1,1): error TS1208: 'empty.ts' cannot be compiled under '--isolatedModules' because it is considered a global script file. Add an import, export, or an empty 'export {}' statement to make it a module.
src/main.ts(1,1): error TS1208: 'main.ts' cannot be compiled under '--isolatedModules' because it is considered a global script file. Add an import, export, or an empty 'export {}' statement to make it a module.
src/types.ts(1,1): error TS1208: 'types.ts' cannot be compiled under '--isolatedModules' because it is considered a global script file. Add an import, export, or an empty 'export {}' statement to make it a module.

作っただけでまだ何も書いていないファイルや、import をコメントアウトして確かめている途中のファイルでも、このエラーは出ます。global.d.ts にはエラーが出ませんでした。

TypeScript は、import 文か export 文が1つでもあるファイルをモジュールとして扱い、どちらもないファイルはグローバルスコープで動くスクリプトとして扱います(TypeScript 4.7 のリリースノート)。isolatedModules の説明によると、このオプションは、1ファイルずつしか変換しないツールでは正しく扱えない書き方を、TypeScript に警告させるためのものです。コードの動きや、TypeScript の型チェックと出力の仕方は変えません。

ファイルの末尾に export {} を書いてモジュールにする

エラーのメッセージが案内しているとおり、ファイルの末尾に export {}; を足しました。

ts
const message: string = "hello";
console.log(message);

export {};

npx tsc は何も出力せずに終了コード 0 になりました。export {}; は何も公開しませんが、export 文なので、TypeScript はこのファイルをモジュールとして扱います。

エラーが出ているファイルが少ないときや、空のファイルを一時的に置いているだけのときは、この直し方が手軽です。ただ、ファイルを作るたびに書く必要があります。

tsconfig.json ですべてのファイルをモジュールとして扱う

ファイルには手を付けず、tsconfig.json の compilerOptions に "moduleDetection": "force" を足しました。

json
{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true
  },
  "include": ["src"]
}

export {}; を書いていない元の src/main.ts のままで、npx tsc は終了コード 0 になりました。

moduleDetection は TypeScript 4.7 で入ったオプションです。moduleDetection の説明によると、"force" は宣言ファイル(.d.ts)以外のすべてのファイルをモジュールとして扱います。プロジェクトのファイルをすべてモジュールとして書いているなら、こちらのほうがファイルごとの手間がかかりません。4.7 より前の TypeScript では使えないので、その場合はファイルに export {}; を書きます。

注意

isolatedModules を false にしても、TS1208 は消えます(npx tsc --isolatedModules false で終了コード 0 になりました)。ただし、1ファイルずつ変換するツールで正しく扱えない書き方への警告も、まとめて出なくなります。Vite などを使うプロジェクトでは、isolatedModules は true のままにして、上の2つのやり方のどちらかで直します。

TypeScript 5.0 以降のバージョンでは TS1208 が出なかった

4.9.5 と同じ src/main.ts(export {}; なし)で、TypeScript 5.0.2、5.9.3、7.0.2 を試しました。5.0.2 と 5.9.3 は、4.9.5 と同じ tsconfig.json のままで npx tsc が終了コード 0 になり、TS1208 は出ませんでした。7.0.2 は moduleResolution の node を受け付けず、TS5108 のエラーで止まりました。そこで3つとも moduleResolution だけを bundler に替えて試すと、どれも終了コード 0 でした。

インストールしたパッケージの中も確かめました。4.9.5 の lib/tsc.js には TS1208 のメッセージ(considered a global script file)が1か所ありましたが、5.0.2 の lib/tsc.js には見つかりませんでした。TypeScript のリポジトリでは、2023年1月に main ブランチにマージされた、verbatimModuleSyntax を足すプルリクエストの中に、「Add tests for loosened isolatedModules script checks」(スクリプトに対する isolatedModules のチェックを緩めたことのテスト)というコミットがあります。

TS1208 が出ているプロジェクトでは、npx tsc -v で TypeScript のバージョンを確かめ、5.0 より前かどうかを見ておくと、原因の見当がつけやすくなります。私が試した 4.9.5 では、export {}; と moduleDetection のどちらのやり方でも消えました。

5.0 以降でも、namespace を書いたスクリプトは TS1280 になる

5.0 以降でも、import も export もないファイルに namespace を書くと、別のエラーになりました。src/util.ts を次の内容にしました。

ts
namespace Util {
  export const version = 1;
}
console.log(Util.version);

5.0.2、5.9.3、7.0.2 のどれでも、次のエラーが出ました(終了コードは 5.x が 2、7.0.2 が 1 でした)。

console
$ npx tsc
src/util.ts(1,11): error TS1280: Namespaces are not allowed in global script files when 'isolatedModules' is enabled. If this file is not intended to be a global script, set 'moduleDetection' to 'force' or add an empty 'export {}' statement.

「isolatedModules が有効なとき、グローバルなスクリプトファイルには namespace を書けません。このファイルをグローバルなスクリプトにするつもりがないなら、moduleDetection を force にするか、空の export {} 文を足してください」という意味です。isolatedModules の説明にも、isolatedModules を有効にすると、namespace は import か export のあるモジュールでしか書けない、とあります。

直し方は TS1208 と同じです。src/util.ts の末尾に export {}; を足すと、3つのバージョンとも終了コード 0 になりました。export {}; を書かずに tsconfig.json に "moduleDetection": "force" を足した場合も、同じく終了コード 0 でした。

​Posted by 86