TypeScriptでimport.metaに出るTS1343の直し方

​​TypeScript​Node.js,トラブルシュート

error TS1343: The 'import.meta' meta-property is only allowed when the '--module' option is ... は、tsconfig.json の module が commonjs や es2015 のような古い値のまま、コードで import.meta を使ったときに tsc が出すエラーです。Node.js で動かすなら "module": "nodenext" に、Vite などのバンドラーに渡すなら "module": "esnext"("moduleResolution": "bundler" と合わせて)に変えると消えます。

Node.js の ES モジュールで import.meta.url からファイルの場所を求めるコードを、module が commonjs の tsconfig.json のまま型チェックすると、このエラーになります。その場面を再現して、直し方を試しました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、npm 10.9.9、TypeScript 5.9.3 です。同じ手順を TypeScript 7.0.2(検証した日の npm の latest)でも試しました。確かめたのは tsc と node の出力だけです。TypeScript 6.x、VS Code などのエディターでの表示、Vite などのバンドラーでのビルド、Deno や Bun は試していません。

直し方は、どこで動かすかで選ぶ

module に何を書くかは、出力したコードをどこで動かすかで決まります。tsconfig リファレンスの module の説明にも、Node.js のプロジェクトなら nodenext、バンドラーに渡すコードなら preserve か esnext がよい、とあります。

動かす場所 tsconfig.json の直し方
Node.js(tsc で出力した .js を実行する) "module": "nodenext" にし、package.json に "type": "module" を書く
Vite などのバンドラー "module": "esnext" と "moduleResolution": "bundler" にする

Node.js で直すときは、package.json の "type": "module" も必要です。これがないと、別の TS1470 というエラーに変わります(あとの節で説明します)。

module が commonjs のままエラーを起こす

空のフォルダーに、"type": "module" を書いた package.json を置き、TypeScript 5.9.3 を入れました。tsconfig.json は次の内容です。

json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "commonjs",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

src/main.ts では、import.meta.url からこのファイルのあるフォルダーの URL を作り、そのプロトコルを表示します。

ts
const here = new URL(".", import.meta.url);
console.log(here.protocol);

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

console
$ npx tsc
src/main.ts(1,27): error TS1343: The 'import.meta' meta-property is only allowed when the '--module' option is 'es2020', 'es2022', 'esnext', 'system', 'node16', 'node18', 'node20', or 'nodenext'.

メッセージは「import.meta を使えるのは、--module が es2020、es2022、esnext、system、node16、node18、node20、nodenext のどれかのときだけです」という意味です。--pretty を付けると、import.meta の下に ~ が付きました(色は省いています)。

console
$ npx tsc --pretty
src/main.ts:1:27 - error TS1343: The 'import.meta' meta-property is only allowed when the '--module' option is 'es2020', 'es2022', 'esnext', 'system', 'node16', 'node18', 'node20', or 'nodenext'.

1 const here = new URL(".", import.meta.url);
                            ~~~~~~~~~~~


Found 1 error in src/main.ts:1

このエラーが出ても、tsc は dist/main.js を出力しました。中身は CommonJS の形で、import.meta はそのまま残っています。

console
$ cat dist/main.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const here = new URL(".", import.meta.url);
console.log(here.protocol);

node dist/main.js を実行すると、package.json の "type": "module" によって ES モジュールとして読まれ、CommonJS にしかない exports が見つからずに止まりました。終了コードは 1 です(パスは /path/to/app に置き換え、先頭のコードの抜き出しと、末尾のスタックトレースは省いています)。

console
$ node dist/main.js
...
ReferenceError: exports is not defined in ES module scope
This file is being treated as an ES module because it has a '.js' file extension and '/path/to/app/package.json' contains "type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.

TS1343 は、CommonJS として出力する設定のまま import.meta を使っていることを知らせています。あとの節の TS1470 のメッセージにもあるとおり、CommonJS として出力するファイルでは import.meta を使えません。

エラーになる module の値

同じ src/main.ts を、--module だけ変えて npx tsc --noEmit で確かめました。5.9.3 の結果は次のとおりです。

module の値 結果
commonjs、es2015、amd、umd、none TS1343
es2020、es2022、esnext エラーなし
node16、node18、node20、nodenext エラーなし
system、preserve エラーなし

preserve はエラーメッセージに並ぶ値には入っていませんが、エラーにはなりませんでした。TypeScript のモジュールのリファレンスには、import.meta に対応したのは es2020 からだと書かれています。es2015 が通らないのはこのためです。tsconfig リファレンスの module の項では、es6 と es2015 は同じ値として並んでいます。

Node.js で動かすなら nodenext にする

tsconfig.json の "module": "commonjs" を "module": "nodenext" に変えました。ほかの行と package.json はそのままです。

json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "nodenext",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src"]
}

npx tsc は何も出力せずに終了コード 0 になり、TS1343 は消えました。出力された dist/main.js は ES モジュールの形になり、node dist/main.js は file: を表示しました。

console
$ cat dist/main.js
const here = new URL(".", import.meta.url);
console.log(here.protocol);
export {};
$ node dist/main.js
file:

nodenext でも type: module がないと TS1470 になる

"module": "nodenext" のまま、package.json から "type": "module" を消すと、TS1343 の代わりに別のエラーが出ました。終了コードは 2 です。

console
$ npx tsc
src/main.ts(1,27): error TS1470: The 'import.meta' meta-property is not allowed in files which will build into CommonJS output.

「CommonJS として出力されるファイルでは import.meta を使えません」という意味です。モジュールのリファレンスにある、モジュール形式の判定についての説明によると、nodenext では、.ts ファイルを ES モジュールと CommonJS のどちらとして扱うかを、いちばん近い上の階層の package.json の "type" で決めます。"type": "module" があれば ES モジュール、なければ CommonJS です。.mts のファイルは、package.json に関係なく ES モジュールになります。

直し方は2つあります。package.json に "type": "module" を書き戻すか、ファイル名を src/main.mts に変えます。.mts に変えたときは、npx tsc が終了コード 0 になり、dist/main.mjs が出力されて、node dist/main.mjs は file: を表示しました。

バンドラーに渡すなら esnext と bundler にする

Vite などのバンドラーが JavaScript を作り、tsc は型チェックだけに使う場合は、次の tsconfig.json にしました。

json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}

npx tsc は終了コード 0 で、TS1343 は出ませんでした。noEmit があるので、dist は作られていません。モジュールのリファレンスでも、esnext と --moduleResolution bundler の組み合わせは、バンドラーや Bun、tsx 向けとされ、Node.js には使わないように書かれています。

module を書いていない tsconfig.json でも出る

tsconfig.json に module の行がなくても、TS1343 は出ます。最初の tsconfig.json から "module": "commonjs" の行だけを消すと、5.9.3 の npx tsc は TS1343 を出しました。npx tsc --showConfig で実際に使われる値を見ると、module は es6 になっていました。

console
$ npx tsc --showConfig | grep -E "\"(target|module|moduleResolution)\""
        "target": "es2022",
        "module": "es6",
        "moduleResolution": "classic",

tsconfig リファレンスによると、module の既定値は、target が es5 なら commonjs、それ以外なら es6(es2015)です。どちらも import.meta に対応していません。module を書いていないときは、--showConfig で何が使われているかを見てから、上の直し方で module を明示するのが確実です。

TypeScript 7.0.2 での結果

TypeScript 7.0.2 でも、"module": "commonjs" の tsconfig.json で TS1343 が出ました。メッセージは 5.9.3 と一字一句同じで、終了コードも 2 でした。nodenext に変えると終了コード 0 になり、node dist/main.js は file: を表示しました。"type": "module" を消したときの TS1470 も、5.9.3 と同じ文面で出ました。また、7.0.2 では "module": "amd" が TS5108(削除されたオプション)、"module": "none" が TS6046(指定できない値)になり、どちらも指定できなくなっていました。

違ったのは、module を書いていない場合です。7.0.2 では、同じ tsconfig.json でエラーは出ず、出力された dist/main.js は ES モジュールの形でした。TypeScript 6.0 のリリースノートに、module の既定値が esnext に変わったと書かれています。この tsconfig.json では、TypeScript を 7.0.2 に上げただけで TS1343 は出なくなりました。

​Posted by 86