動かざることバグの如し

近づきたいよ 君の理想に

esbuildはtsconfig.jsonの設定全てを見ているわけではない

nodejs

環境

  • esbuild 0.27.2

esbuildが参照するtsconfig.jsonのキー一覧

esbuildは、TypeScriptビルド時にtsconfig.jsonファイルを参照するが、すべてのフィールドを尊重するわけではない。

まあ公式ドキュメントに書いてある通りなんだが。

esbuild.github.io

以下は、esbuildが実際に参照・使用するキーを紹介していく。

experimentalDecorators

  • 一般的な使い方: TypeScriptでデコレータ機能を有効にする
  • esbuildでの扱い:
    • 有効な場合: TypeScriptのレガシーデコレータ動作を使用して変換
    • 無効または未設定の場合: 標準JavaScriptデコレータ仕様に従って変換
  • 備考: この設定により、デコレータの実行時の動作が大きく異なる

target

  • 一般的な使い方: 出力するJavaScriptのバージョンを指定（例: ES5, ES2015, ES2022など）
  • esbuildでの扱い:
    • useDefineForClassFieldsのデフォルト値を決定するためにのみ使用
    • targetがES2022未満の場合、useDefineForClassFieldsのデフォルト値はfalse
  • 備考: esbuild自身のtarget設定には影響しない（名前は同じだが別物）

useDefineForClassFields

  • 一般的な使い方: クラスフィールドの動作を制御（定義セマンティクスか代入セマンティクスか）
  • esbuildでの扱い:
    • true（デフォルト動作）: 標準JavaScriptのクラスフィールド動作（定義セマンティクス）
    • false: TypeScriptのレガシー動作（代入セマンティクス、基底クラスのセッターをトリガー）
  • 備考: 明示的に設定することが推奨される。レガシーコードの互換性のために必要な場合がある

baseUrl

  • 一般的な使い方: モジュール解決のベースディレクトリを指定
  • esbuildでの扱い:
  • 備考: バンドルが有効な場合にのみ機能する

paths

  • 一般的な使い方: パスマッピングを定義（例: @/*をsrc/*にマップ）
  • esbuildでの扱い:
    • インポートパスの解決時に使用され、ファイルパスの書き換えを行う
    • パッケージエイリアスの定義などに使用可能
  • 備考: バンドルが有効な場合にのみ機能する。esbuildネイティブのalias機能も検討可能

jsx

  • 一般的な使い方: JSX構文の変換方法を指定（react, react-jsx, preserveなど）
  • esbuildでの扱い:
    • JSX構文をJavaScriptに変換する方法を制御
    • esbuildのネイティブjsxオプションと等価
  • 備考: React以外のJSXライブラリを使用する場合に重要

jsxFactory

  • 一般的な使い方: JSX要素を変換する関数名を指定（デフォルト: React.createElement）
  • esbuildでの扱い:
    • esbuildのネイティブjsxFactoryオプションと等価
    • カスタムJSXファクトリ関数を指定可能
  • 備考: Preactなど他のライブラリを使用する場合に必要（例: h）

jsxFragmentFactory

  • 一般的な使い方: JSXフラグメント（<>...</>）を変換する関数名を指定（デフォルト: React.Fragment）
  • esbuildでの扱い:
    • esbuildのネイティブjsxFragmentオプションと等価
    • カスタムフラグメントファクトリを指定可能
  • 備考: jsxFactoryと合わせて設定する

jsxImportSource

  • 一般的な使い方: 自動JSXランタイムインポート時のインポート元を指定
  • esbuildでの扱い:
    • esbuildのネイティブjsxImportSourceオプションと等価
    • jsx: "react-jsx"またはjsx: "react-jsxdev"と組み合わせて使用
  • 備考: React 17+の新しいJSX変換で使用

alwaysStrict

  • 一般的な使い方: すべてのファイルをstrictモードで解析し、"use strict"を出力
  • esbuildでの扱い:
    • 有効な場合、すべてのTypeScriptファイルがstrictモードとみなされる
    • 生成コードに"use strict"を追加（ESM形式以外の場合）
  • 備考: ESM形式の出力では自動的にstrictモードなので追加されない

strict

  • 一般的な使い方: すべてのstrict型チェックオプションを有効化（alwaysStrictを含む）
  • esbuildでの扱い:
    • alwaysStrictと同様に、strictモードの判定に使用
    • TypeScriptコードに"use strict"を追加
  • 備考: alwaysStrictまたはstrictのいずれかが有効であれば適用

verbatimModuleSyntax

  • 一般的な使い方: インポート/エクスポート構文をそのまま保持（TypeScript 5.0+）
  • esbuildでの扱い:
    • 未使用のインポートを削除しないように制御
    • 副作用のあるインポートを保持したい場合に有効
  • 備考: importsNotUsedAsValuesとpreserveValueImportsを置き換える新しいオプション

importsNotUsedAsValues (非推奨)

  • 一般的な使い方: 型としてのみ使用されるインポートの扱いを制御
  • esbuildでの扱い:
    • デフォルトでは未使用のインポートを削除
    • この設定で削除動作をカスタマイズ可能
  • 備考: TypeScriptで非推奨。代わりにverbatimModuleSyntaxを使用

preserveValueImports (非推奨)

  • 一般的な使い方: 値インポートを保持
  • esbuildでの扱い:
    • 未使用のインポートを保持する動作を制御
    • 副作用のあるモジュールに有用
  • 備考: TypeScriptで非推奨。代わりにverbatimModuleSyntaxを使用

extends

  • 一般的な使い方: 他のtsconfig.jsonファイルから設定を継承
  • esbuildでの扱い:
    • 設定ファイルの継承をサポート
    • 文字列（単一継承）または配列（複数継承、TypeScript 5.0+）が可能
  • 備考: 設定を複数ファイルに分割できる