Node.jsのERR_UNKNOWN_FILE_EXTENSIONの直し方
node app.tsx や node hello.ts を実行したときに TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".tsx" が出て止まるのは、Node.js がその拡張子のファイルの読み方を知らないからです。Node.js は新しい版でも .tsx を実行できず、古い版では .ts も実行できません。.tsx は tsx(TypeScript を Node.js で実行するための npm パッケージ)で実行し、.ts は Node.js を 22.18.0 以降に上げるか tsx を使うと、エラーは消えます。
React のコンポーネントを .tsx で書き、サーバー側の描画(renderToString)やテスト用のスクリプトとして node コマンドでそのまま実行しようとしたときや、TypeScript で書いた CLI やスクリプトをビルドせずに動かそうとしたときに出るエラーです。私は Node.js の4つのバージョンでエラーを起こし、出たメッセージと、直したあとに消えることを確かめました。
検証環境は Ubuntu 24.04(x86_64)で、Node.js 20.18.3、22.12.0、22.23.4、24.22.1 を使いました。20.18.3 と 22.12.0 は nodejs.org で配布されている Linux 用のバイナリです。npm のパッケージは tsx 4.23.15、typescript 7.0.2、react と react-dom 19.3.1 です。Windows と macOS、Node.js 23 系、ts-node や Bun・Deno などほかの実行のしかた、Jest や webpack などのツールの中で出る同じエラーは試していません。
.tsx を node で実行したときのエラー
npm init -y のあと npm pkg set type=module で package.json に "type": "module" を足し、react と react-dom を入れました。実行したのは、React のコンポーネントを HTML の文字列にして表示する app.tsx です。
import { renderToString } from 'react-dom/server';
function Greeting({ name }: { name: string }) {
return <p>hello, {name}</p>;
}
console.log(renderToString(<Greeting name="tsx" />));
Node.js 22.23.4 で node app.tsx を実行すると、次のように出て止まりました(終了コードは1。パスは例示用の値に置き換えています)。
$ node app.tsx
node:internal/modules/esm/get_format:219
throw new ERR_UNKNOWN_FILE_EXTENSION(ext, filepath);
^
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".tsx" for /path/to/app/app.tsx
at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:219:9)
at defaultGetFormat (node:internal/modules/esm/get_format:245:36)
at defaultLoadSync (node:internal/modules/esm/load:166:16)
at ModuleLoader.load (node:internal/modules/esm/loader:831:12)
at ModuleLoader.loadAndTranslate (node:internal/modules/esm/loader:609:31)
at #createModuleJob (node:internal/modules/esm/loader:640:36)
at #getJobFromResolveResult (node:internal/modules/esm/loader:353:34)
at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:321:41)
at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:680:25) {
code: 'ERR_UNKNOWN_FILE_EXTENSION'
}
Node.js v22.23.4
TypeError [ERR_UNKNOWN_FILE_EXTENSION] の行は「app.tsx の拡張子 .tsx を知らない」という意味です。Node.js のエラーの一覧でも、知らない拡張子や対応していない拡張子のモジュールを読み込もうとしたときのエラーと説明されています。スタックがすべて node:internal/modules/esm/ の中なのは、ES モジュールとしてファイルを読み込む途中で、拡張子からファイルの形式を決めようとして止まったからです。
Node.js 24.22.1 でも、TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".tsx" for /path/to/app/app.tsx という同じ行が出ました。違ったのは、1行目の get_format:243 のような内部の行番号と、スタックの中身だけです。
Node.js 22.18.0 からは .ts を設定なしで実行できますが、.tsx は対象に入っていません。Node.js の TypeScript のドキュメントには「.tsx files are unsupported.」とあり、Node.js 24 の同じページにも同じ一文があります。同じページによると、Node.js は型の注釈を取り除くだけで、TypeScript の書き方を別の JavaScript に書き換える必要がある機能には対応していません。JSX(<p>…</p> のような書き方)も、関数の呼び出しに書き換えないと実行できない書き方です。
古い Node.js では .ts でも同じエラーになる
型の注釈だけを含む hello.ts を、同じプロジェクト("type": "module" あり)で実行しました。
const name: string = 'world';
console.log(`hello, ${name}`);
Node.js 20.18.3 では、拡張子が .ts になっただけで、同じエラーが出ました。
$ node hello.ts
node:internal/modules/esm/get_format:176
throw new ERR_UNKNOWN_FILE_EXTENSION(ext, filepath);
^
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /path/to/app/hello.ts
at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:176:9)
at defaultGetFormat (node:internal/modules/esm/get_format:219:36)
at defaultLoad (node:internal/modules/esm/load:143:22)
at async ModuleLoader.load (node:internal/modules/esm/loader:555:7)
at async ModuleLoader.moduleProvider (node:internal/modules/esm/loader:434:45)
at async link (node:internal/modules/esm/module_job:87:21) {
code: 'ERR_UNKNOWN_FILE_EXTENSION'
}
Node.js v20.18.3
Node.js 22.12.0 でも TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /path/to/app/hello.ts が出て、終了コードは1でした。一方、22.23.4 と 24.22.1 では、同じ node hello.ts で hello, world と表示されて終わりました。
この違いは、Node.js が .ts を実行する機能(型を取り除く機能)が、いつ既定で有効になったかで決まります。Node.js 22 の TypeScript のドキュメントによると、この機能は 22.6.0 で追加され、22.18.0 で既定で有効になりました。Node.js 24 の同じページによると、23 系では 23.6.0 で既定で有効になりました。それより前の版では、.ts は知らない拡張子として扱われます。
package.json に "type" がないと SyntaxError になる
同じ Node.js 20.18.3 でも、package.json から "type" を消す(npm pkg delete type)と、ERR_UNKNOWN_FILE_EXTENSION ではなく次のエラーになりました。
$ node hello.ts
/path/to/app/hello.ts:1
const name: string = 'world';
^^^^
SyntaxError: Missing initializer in const declaration
at wrapSafe (node:internal/modules/cjs/loader:1378:20)
at Module._compile (node:internal/modules/cjs/loader:1428:41)
at Module._extensions..js (node:internal/modules/cjs/loader:1548:10)
at Module.load (node:internal/modules/cjs/loader:1288:32)
at Module._load (node:internal/modules/cjs/loader:1104:12)
at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:173:12)
at node:internal/main/run_main_module:28:49
Node.js v20.18.3
スタックが cjs/loader の Module._extensions..js を通っています。CommonJS(require を使う、Node.js に元からある形式)の読み込みでは、知らない拡張子のファイルを .js と同じように JavaScript として読もうとし、: string の型の注釈のところで構文エラーになっています。Node.js の CommonJS のドキュメントにも、.json と .node 以外の拡張子のファイルは JavaScript のテキストとして読むと書かれています。どちらのエラーも、原因は Node.js がこのファイルを TypeScript として読めないことです。"type" がないままでも、このあと紹介する tsx で npx tsx hello.ts を実行した場合と、Node.js 22.23.4 で node hello.ts を実行した場合は、どちらも hello, world と表示されました。
直し方1:.tsx は tsx で実行する
tsx は、TypeScript と JSX を JavaScript に変換しながら Node.js で実行する npm パッケージです。Node.js の TypeScript のドキュメントでも、tsconfig.json を含めて TypeScript の機能をすべて使いたいときの外部パッケージの例として、tsx が挙げられています。開発用の依存として入れて、npx tsx で実行します。
npm install --save-dev tsx
npx tsx app.tsx
検証環境では、npm install -D tsx typescript @types/react @types/react-dom で、型チェックに使う typescript や React の型定義と一緒に入れました(-D は --save-dev の短い書き方です)。
tsconfig.json には "jsx": "react-jsx" を書きました。TypeScript の tsconfig.json のリファレンスによると、JSX を _jsx という関数の呼び出しに変換する設定です。app.tsx のように React を import していないファイルも、この設定で動きました。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"jsx": "react-jsx",
"strict": true,
"allowImportingTsExtensions": true,
"noEmit": true
}
}
node app.tsx でエラーになった同じファイルを npx tsx app.tsx で実行すると、エラーは出ず、React が作った HTML が表示されました。
$ npx tsx app.tsx
<p>hello, <!-- -->tsx</p>
node コマンドのまま実行したいときは、--import tsx を付けて、tsx を先に読み込ませます。Node.js 20.18.3、22.12.0、22.23.4、24.22.1 のどれでも、同じ出力になりました。
$ node --import tsx app.tsx
<p>hello, <!-- -->tsx</p>
ファイルを直接実行するときだけでなく、.ts から .tsx を import したときにも同じエラーが出ます。./Greeting.tsx を読み込む main.ts を Node.js 22.23.4 で node main.ts として実行すると、import した Greeting.tsx について Unknown file extension ".tsx" for /path/to/app/Greeting.tsx が出て止まりました。エラーに出るファイル名が、実行したファイルではなく読み込まれた側になっている点に気をつけてください。これも npx tsx main.ts で実行すると、<p>hello, <!-- -->main</p> と表示されました。
直し方2:.ts は Node.js を上げるか、フラグを付けるか、tsx を使う
.ts だけなら、Node.js を 22.18.0 以降(23 系なら 23.6.0 以降)に上げるのがいちばん手軽です。検証環境の 22.23.4 と 24.22.1 では、何も足さずに node hello.ts が動きました。
Node.js を上げられず、22.6.0〜22.17.x の範囲を使っているときは、--experimental-strip-types を付けると動きます。22.12.0 で試したところ、実験的な機能だという警告のあとに、正しく実行されました。
$ node --experimental-strip-types hello.ts
(node:4012) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
hello, world
Node.js 20 には、このフラグがありません。20.18.3 で付けると、bad option: --experimental-strip-types と出て、終了コード9で止まりました。Node.js 20 のままなら tsx を使います。PATH の先頭を Node.js 20.18.3 にして(npx tsx --version で node v20.18.3 と出ることを確かめてから)実行すると、npx tsx hello.ts は hello, world を、npx tsx app.tsx は <p>hello, <!-- -->tsx</p> を表示しました。
| 実行のしかた | 20.18.3 | 22.12.0 | 22.23.4 / 24.22.1 |
|---|---|---|---|
node hello.ts |
エラー | エラー | 動く |
node --experimental-strip-types hello.ts |
bad option | 動く(警告あり) | 動く |
npx tsx hello.ts |
動く | 動く | 動く |
node app.tsx |
エラー | エラー | エラー |
npx tsx app.tsx |
動く | 動く | 動く |
エラーが消えても、型の誤りは見つからない
tsx も Node.js の .ts の実行も、型のチェックはしません。Node.js の TypeScript のドキュメントにも、型の注釈を空白に置き換えるだけで型のチェックはしないとあります。数値の変数に文字列を入れた次の typo.ts は、npx tsx typo.ts でも、Node.js 22.23.4 の node typo.ts でも、エラーなしで three と表示されました。
const count: number = 'three';
console.log(count);
型の誤りを見つけるには、TypeScript の tsc を別に実行します。同じプロジェクトで npx tsc --noEmit を実行すると、次のエラーが出て、終了コードは1でした。
$ npx tsc --noEmit
typo.ts(1,7): error TS2322: Type 'string' is not assignable to type 'number'.
上の tsconfig.json に "allowImportingTsExtensions": true を書いたのは、main.ts のように import のパスを .tsx で終えているからです。typo.ts を消し、コマンドでこの設定だけを外して tsc を実行すると、次のエラーになりました。
$ npx tsc --noEmit --allowImportingTsExtensions false
main.ts(3,26): error TS5097: An import path can only end with a '.tsx' extension when 'allowImportingTsExtensions' is enabled.
tsconfig.json のリファレンスの allowImportingTsExtensions の説明によると、この設定は noEmit か emitDeclarationOnly を有効にしているときだけ使えます。





