@babel/plugin-transform-typescript

情報

このプラグインは @babel/preset-typescript に含まれています。

このプラグインは、TypeScriptプログラミング言語で使用される型構文のサポートを追加します。ただし、このプラグインは、渡されたJavaScriptの型チェック機能を追加するものではありません。そのためには、TypeScriptをインストールして設定する必要があります。

TypeScriptコンパイラtscは、オプションチェーン (?.)、null合体 (??)、クラスプロパティ (this.#x) などの特定のJavaScript提案を積極的にサポートしていますが、このプリセットにはこれらの機能は含まれていないことに注意してください。これらはTypeScriptでのみ利用可能な型構文ではないためです。これらの機能をトランスパイルしたい場合は、preset-env を preset-typescript と一緒に使用することをお勧めします。

例

入力

const x: number = 0;

出力

const x = 0;

インストール

npm

npm install --save-dev @babel/plugin-transform-typescript

Yarn

yarn add --dev @babel/plugin-transform-typescript

pnpm

pnpm add --save-dev @babel/plugin-transform-typescript

使用法

構成ファイルを使用する（推奨）

babel.config.json

{
  "plugins": ["@babel/plugin-transform-typescript"]
}

CLI経由

シェル

babel --plugins @babel/plugin-transform-typescript script.js

Node API経由

JavaScript

require("@babel/core").transformSync("code", {
  plugins: ["@babel/plugin-transform-typescript"],
});

オプション

allowDeclareFields

boolean、デフォルトは false

v7.7.0 で追加

注

これはBabel 8でデフォルトで有効になります。

有効にすると、型のみのクラスフィールドは、declare修飾子がプレフィックスとして付いている場合にのみ削除されます。

JavaScript

class A {
  declare foo: string; // Removed
  bar: string; // Initialized to undefined
}

allowNamespaces

boolean、デフォルトは true。

履歴

バージョン	変更点
v7.5.0	allowNamespaces を追加、デフォルトは false
v7.13.0	デフォルトは true

TypeScript名前空間のコンパイルを有効にします。

disallowAmbiguousJSXLike

boolean、デフォルトは false

追加：v7.16.0

JSXの解析が有効になっていない場合でも、このオプションはJSXとあいまいな構文 (<X> y 型アサーションと <X>() => {} 型引数) の使用を禁止します。これは、.mts および .mjs ファイルを解析する際の tsc の動作と一致します。

dts

boolean、デフォルトは false

追加：v7.20.0

このオプションは、特定の構文に異なるルールがあるTypeScriptのアンビエントコンテキスト内 (.d.ts ファイルや declare module ブロック内など) での解析を有効にします。アンビエントコンテキストの詳細については、公式ハンドブックとTypeScript Deep Diveを参照してください。

isTSX

boolean、デフォルトは false

強制的に jsx 解析を有効にします。そうしない場合、山括弧はTypeScriptの従来の型アサーション var foo = <string>bar; として扱われます。また、isTSX: true には allExtensions: true が必要です。

jsxPragma

string、デフォルトは React

JSX式をコンパイルする際に使用される関数を置き換えます。これにより、インポートが型インポートではなく、削除されるべきではないことがわかります。

jsxPragmaFrag

string、デフォルトは React.Fragment

JSXフラグメント式をコンパイルする際に使用される関数を置き換えます。これにより、インポートが型インポートではなく、削除されるべきではないことがわかります。

onlyRemoveTypeImports

boolean、デフォルトは false

追加：v7.9.0

true に設定すると、変換は型のみのインポート（TypeScript 3.8で導入）のみを削除します。これは、TypeScript >= 3.8を使用している場合にのみ使用する必要があります。

JavaScript

class A {
  declare foo: string; // Removed
  bar: string; // Initialized to undefined
  prop?: string; // Initialized to undefined
  prop1!: string // Initialized to undefined
}

optimizeConstEnums

boolean、デフォルトは false

追加：v7.15.0

trueに設定すると、Babelは通常のenum出力を使用するのではなく、enum値をインライン化します

// Input
const enum Animals {
  Fish,
}
console.log(Animals.Fish);

// Default output
var Animals;

(function(Animals) {
  Animals[(Animals["Fish"] = 0)] = "Fish";
})(Animals || (Animals = {}));

console.log(Animals.Fish);

// `optimizeConstEnums` output
console.log(0);

このオプションは、const修飾子を無視して通常のenumとしてコンパイルするTypeScriptの--isolatedModules動作とは異なり、Babelの動作をTypeScriptのデフォルト動作に合わせます。

ただし、const enumをエクスポートする場合、Babelはコンパイル時にクロスファイル分析に依存する必要がないように、プレーンなオブジェクトリテラルにコンパイルします

// Input
export const enum Animals {
  Fish,
}

// `optimizeConstEnums` output
export var Animals = {
  Fish: 0,
};

TypeScriptコンパイラオプション

公式のTypeScriptコンパイラには、コンパイル方法と型チェック方法を構成するための多くのオプションがあります。多くは適用されませんが、いくつかの動作は役立つ可能性があり、Babelでの同等の動作は、いくつかの構成オプションまたはプラグインで有効にできます。

• --alwaysStrict strictMode パーサーオプションを使用できます。

  JavaScript

  module.exports = {
    parserOpts: { strictMode: true },
  };

• --downlevelIteration @babel/plugin-transform-for-ofプラグインを使用できます。 @babel/preset-envを使用している場合、コンパイルターゲットでサポートされていない場合、for...ofはイテレーターを使用して既にトランスパイルされています。

• --emitDecoratorMetadata このオプションは、TypeScript固有の追加であり、デコレーター提案の一部ではないため、公式のBabelパッケージではサポートされていません。この機能に依存している場合は、コミュニティプラグイン babel-plugin-transform-typescript-metadata を使用できます。

• --esModuleInterop これは、ECMAScriptモジュールをトランスパイルする際のBabelのデフォルトの動作です。

• --experimentalDecorators このオプションは、「レガシー」デコレーター提案のサポートを有効にします。 @babel/plugin-proposal-decoratorsプラグインを使用してBabelで有効にできますが、いくつかのわずかな違いがあることに注意してください。

  JavaScript

  module.exports = {
    plugins: [["@babel/plugin-proposal-decorators", { legacy: true }]],
  };

• --importHelpers これは、@babel/plugin-transform-runtimeパッケージと同等です。

• ---importsNotUsedAsValues この動作を再現するには、onlyRemoveTypeImportsオプションを使用できます。 onlyRemoveTypeImports: true は importsNotUsedAsValues: preserve と同等であり、 onlyRemoveTypeImports: false は importsNotUsedAsValues: remove と同等です。 importsNotUsedAsValues: error に相当するものはありません。

• --inlineSourceMap babel.config.jsonファイルでsourceMaps: "inline"オプションを設定できます。

• --isolatedModules これはBabelのデフォルトの動作であり、Babelはクロスファイル分析をサポートしていないため、オフにすることはできません。

• --jsx JSXサポートは別のプラグインを使用して提供されます。出力にJSXコードを含める場合 (つまり --jsx preserve)、@babel/plugin-syntax-jsxプラグインが必要です。標準のJavaScriptにトランスパイルする場合 (つまり、--jsx react または --jsx react-native)、@babel/plugin-transform-react-jsxプラグインを使用する必要があります。

• --jsxFactory pragmaオプション を使用してカスタマイズできます。また、このプラグインのjsxPragmaオプションを設定する必要があります。

• --module, -m バンドラー（WebpackまたはRollup）を使用している場合、このオプションは自動的に設定されます。 @babel/preset-envを使用している場合は、modulesオプションを使用できます。それ以外の場合は、特定のプラグインをロードできます。

  --module 値	@babel/preset-env の modules	単一プラグイン
  なし	false	/
  CommonJS	"commonjs" または "cjs"	@babel/plugin-transform-modules-commonjs
  AMD	"amd"	@babel/plugin-transform-modules-amd
  System	"systemjs"	@babel/plugin-transform-modules-systemjs
  UMD	"umd"	@babel/plugin-transform-modules-umd
  ES6 または ES2015	false	/

• --outDir @babel/cliを使用する場合、--out-dirオプションを設定できます。

• --outFile Babelは出力ファイルの連結をサポートしていません。そのため、バンドラー（Webpack、Rollup、Parcelなど）を使用する必要があります。@babel/cliを使用する場合は、--out-fileオプションを使用して単一のファイルをコンパイルできます。

• --sourceMap トップレベルのsourceMaps: trueオプションを使用できます。

• --target Babelは特定の言語バージョンをターゲットにすることをサポートしていませんが、@babel/preset-envを使用して、ターゲットとするエンジンを選択できます。または、すべてのECMAScript機能に対して個別のプラグインを有効にすることもできます。

• --useDefineForClassFields この動作を再現するには、setPublicClassFieldsの前提を使用できます。

• --watch, -w @babel/cliを使用する場合は、--watchオプションを指定できます。

注意点

TypeScript言語には、実行時に変更を加えるために完全な型システムが利用可能であることに依存する機能があるため、注意点に関するこのセクションは長くなっています。ただし、これらの機能のいくつかは古いTypeScriptコードベースにのみ存在し、現在はおそらくすでに使用している最新のJavaScriptと同等のものがあることに注意してください。

1. Babelは型チェックを行わないため、構文的には正しいが、TypeScriptの型チェックに失敗するコードは、変換に成功する可能性があり、予期しない、または無効な方法で変換されることがよくあります。

2. tsconfig.jsonへの変更は、Babelには反映されません。ビルドプロセスは、常にisolatedModulesがオンになっているかのように動作します。ただし、tsconfig.jsonオプションの多くを設定するためのBabelネイティブの代替方法があります。

3. Q: なぜBabelはvarまたはletのエクスポートを許可しないのですか？

   A: TypeScriptコンパイラは、これらの変数が変更されるかどうかに応じて、これらの変数の使用方法を動的に変更します。最終的に、これは型モデルに依存し、Babelの範囲外です。最善を尽くした実装では、変数が現在のファイルの外部で変更された場合に備えて、コンテキスト依存の変数の使用を、常にValueではなくNamespace.Valueバージョンを使用するように変換します。Babelからvarまたはletを許可すること（変換はまだ記述されていない）は、constではないかのように使用された場合にバグとして現れる可能性が高くなります。

部分的な名前空間のサポート

TypeScriptのみの名前空間機能を使用する既存のコードがある場合、BabelはTypeScriptの名前空間機能のサブセットをサポートしています。名前空間を使用する新しいコードを作成することを検討している場合は、代わりにES2015のimport/exportを使用することをお勧めします。それはなくなるわけではありませんが、現代的な代替手段があります。

• 型のみのnamespaceはdeclareでマークする必要があり、その後安全に削除されます。

• namespace内でvarまたはletを使用して変数をexportすると、エラーが発生します：「名前空間は、const以外のものをエクスポートすることは、Babelではサポートされていません。constまたは...に変更してください。」

  回避策: constを使用します。何らかの変更が必要な場合は、内部の可変性を持つオブジェクトを明示的に使用します。

• namespaceはスコープを共有しません。TypeScriptでは、namespaceが拡張するコンテキストアイテムを修飾なしで参照することは有効であり、コンパイラは修飾子を追加します。Babelには型モデルがなく、親オブジェクトの確立された型に合わせて参照を動的に変更することは不可能です。

  次のコードを検討してください。

  namespace N {
    export const V = 1;
  }
  namespace N {
    export const W = V;
  }

  TypeScriptコンパイラは、次のようなものにコンパイルします。

  JavaScript

  var N = {};
  (function(N) {
    N.V = 1;
  })(N);
  (function(N) {
    N.W = N.V;
  })(N);

  一方、Babelは次のようなものに変換します。

  JavaScript

  var N;
  (function(_N) {
    const V = (_N = 1);
  })(N || (N = {}));
  (function(_N) {
    const W = V;
  })(N || (N = {}));

  BabelはNの型を理解していないため、Vへの参照はundefinedになり、エラーが発生します。

  回避策: TypeScriptによればスコープ内にある場合でも、同じ名前空間定義にない値を明示的に参照します。例

  namespace N {
    export const V = 1;
  }
  namespace N {
    export const W = N.V;
  }

  または

  namespace N {
    export const V = 1;
    export const W = V;
  }