@babel/plugin-transform-typescript

ПРИМЕЧАНИЕ: Этот плагин включён в @babel/preset-typescript

Этот плагин добавляет поддержку синтаксиса типов, используемого языком программирования TypeScript. Однако этот плагин не добавляет возможность проверки типов переданного ему JavaScript-кода. Для этого вам потребуется установить и настроить TypeScript.

Обратите внимание, что, хотя компилятор TypeScript tsc активно поддерживает определённые предложения JavaScript, такие как опциональную цепочку (?.), нулевое слияние (??) и свойства классов (this.#x), этот пресет не включает эти возможности, потому что они не относятся к синтаксису типов, доступному только в TypeScript. Мы рекомендуем использовать preset-env с preset-typescript, если вы хотите транспилировать эти возможности.

Пример​

Вход

const x: number = 0;

Выход

const x = 0;

Установка​

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

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

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

Использование​

С файлом конфигурации (Рекомендуется)​

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

Через командную строку​

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

Через API Node.js​

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

Настройки​

allowDeclareFields​

boolean, по умолчанию false

Добавлена в v7.7.0

ПРИМЕЧАНИЕ: Эта настройка будет включена по умолчанию в Babel 8

При включении, поля класса только для типов удаляются только если они имеют префикс модификатором declare:

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

allowNamespaces​

boolean, по умолчанию true

Включает компиляцию пространств имён TypeScript.

disallowAmbiguousJSXLike​

boolean, по умолчанию false

Добавлена в: v7.16.0

Даже когда парсинг JSX не включён, эта опция запрещает использование синтаксиса, который был бы неоднозначным с JSX (<X> y утверждения типов и <X>() => {} аргументы типов). Она соответствует поведению tsc при парсинге .mts и .mjs файлов.

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.

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 вывода:

// 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);

Эта настройка отличается от поведения TypeScript --isolatedModules, которое игнорирует модификатор const и компилирует их как обычные перечисления, и согласуется с поведением по умолчанию TypeScript.

Однако при экспорте const enum Babel будет компилировать его в обычную литерал объекта, чтобы не зависеть от анализа по файлам при его компиляции:

// Input
export const enum Animals {
  Fish,
}

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

Настройки компилятора TypeScript​

Официальный компилятор TypeScript имеет множество настроек для конфигурирования компиляции и проверки типов. Хотя многие из них не применимы, некоторые поведения могут быть полезны, и их аналоги в Babel могут быть включены с помощью некоторых настроек конфигурации или плагинов.

• --alwaysStrict Вы можете использовать strictMode опцию парсера:

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

• --downlevelIteration Вы можете использовать @babel/plugin-transform-for-of плагин. Если вы используете @babel/preset-env, for...of уже транспилируется с использованием итераторов, если это не поддерживается вашей/вашими целевыми компиляцией(ями).

• --emitDecoratorMetadata Эта опция не поддерживается официальным пакетом Babel, так как это специфическое дополнение TypeScript, а не часть предложения по дескрипторам. Если вы полагаетесь на эту функцию, вы можете использовать плагин сообщества babel-plugin-transform-typescript-metadata.

• --esModuleInterop Это стандартное поведение Babel при транспиляции модулей ECMAScript.

• --experimentalDecorators Эта опция включает поддержку предложения по дескрипторам «legacy». Вы можете включить её в Babel, используя @babel/plugin-proposal-decorators плагин, но имейте в виду, что есть некоторые незначительные различия.

  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 Вы можете задать sourceMaps: "inline" опцию в вашем babel.config.json файле.

• --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 опцию пакета @babel/plugin-transform-react-jsx . Вам также необходимо задать jsxPragma опцию этого плагина.

• --module, -m Если вы используете бандлер (Webpack или Rollup), эта опция устанавливается автоматически. Если вы используете @babel/preset-env, вы можете использовать modules опцию; в противном случае вы можете загрузить конкретный плагин.

  --module значение	@babel/preset-env's modules	Один плагин
  None	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 Вы можете использовать onlyRemoveTypeImports опцию для воспроизведения этого поведения.

• --watch, -w При использовании @babel/cli, вы можете указать --watch опцию.

Особые случаи​

Поскольку существуют особенности языка TypeScript, которые полагаются на полную систему типов, чтобы вносить изменения во время выполнения. Этот раздел особых случаев довольно длинный, однако стоит отметить, что некоторые из этих особенностей встречаются только в старых кодовых базах TypeScript и имеют современные эквиваленты в JavaScript, которые вы, вероятно, уже используете.

1. Поскольку Babel не выполняет проверку типов, код, который синтаксически корректен, но не прошёл проверку типов TypeScript, может успешно быть преобразован, и часто неожиданным или некорректным способом.

2. Этот плагин не поддерживает export = и import =, так как они не могут быть скомпилированы в ES.next. Это специфические для TypeScript формы import/export.

   Обходные пути:

   • Используйте плагин babel-plugin-replace-ts-export-assignment, чтобы преобразовать export =.
   • Перейдите к использованию export default и export const, а также import x, {y} from "z".

3. Изменения в вашем tsconfig.json не отражаются в Babel. Процесс сборки всегда будет вести себя так, как будто isolatedModules включён, однако существуют собственные методы Babel для задания многих tsconfig.json опций.

4. В: Почему Babel не позволяет экспортировать var или let?

   О: Компилятор TypeScript динамически изменяет способ использования этих переменных в зависимости от того, изменяется ли значение. В конечном счёте, это зависит от модели типов и выходит за рамки Babel. Реализация с наилучшими усилиями преобразует контекстно-зависимые использования переменной таким образом, чтобы всегда использовалась версия Namespace.Value, а не Value, если она была изменена вне текущего файла. Поэтому разрешение экспорта var или let в Babel (поскольку трансформация ещё не написана) скорее всего приведёт к ошибке, если использовать её как будто она не const.

Поддержка пространств имён​

Если у вас есть существующий код, использующий специфичные для TypeScript возможности пространств имён. Babel поддерживает подмножество возможностей пространств имён TypeScript. Если вы рассматриваете написание нового кода, использующего пространства имён, рекомендуется использовать ES2015 import/export вместо этого. Оно не исчезнет, но существуют современные альтернативы.

• Только типы namespace должны быть помечены declare и впоследствии будут безопасно удалены.

• export переменной, используя var или let в namespace, приведёт к ошибке: «Не поддерживаются пространства имён, экспортирующие не-константы. Измените на const или…»

  Обходной путь: Используйте const. Если требуется какая-либо форма изменения, используйте объект с внутренней изменчивостью.

• namespace не будут совместно использовать своё пространство. В TypeScript допустимо ссылаться на контекстные элементы, которые namespace наследует, без квалификации, и компилятор добавит квалификатор. В Babel нет модели типов, и невозможно динамически изменить ссылки, чтобы соответствовать установленному типу родительского объекта.

  Рассмотрим этот код:

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

  Компилятор TypeScript преобразует его в нечто подобное:

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

  В то время как Babel преобразует его во что-то вроде этого:

  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;
  }