Babel Preset for TypeScript Proposals

4.0.0 · active · verified Sun Apr 19

The `babel-preset-proposal-typescript` (currently v4.0.0) is a Babel preset designed to enable experimental ECMAScript proposals in TypeScript projects that TypeScript itself does not yet natively support. This includes features like async do expressions, record and tuple, pipeline operator, and more, allowing developers to utilize cutting-edge syntax while still leveraging TypeScript's type-checking capabilities for standard features. The preset maintains an active development pace, with major versions typically aligned with updates to its core peer dependencies: `@babel/core` (currently `^7.23.0`) and `typescript` (currently `^5.3.0`). Its primary differentiator is its focused scope: it specifically fills the gap for proposals that the TypeScript team explicitly postpones or chooses not to implement, avoiding redundant transformations with `@babel/preset-typescript` or other standard presets.

Common errors

```
Cannot find module 'babel-preset-proposal-typescript'
```
cause The package is not installed or incorrectly referenced in `package.json`.

fix Ensure `babel-preset-proposal-typescript` is listed in your `devDependencies` and installed: `npm install --save-dev babel-preset-proposal-typescript` or `yarn add -D babel-preset-proposal-typescript`.
```
Requires Babel '^7.23.0'
```
cause Your installed `@babel/core` version does not meet the peer dependency requirement of `babel-preset-proposal-typescript@4.0.0`.

fix Upgrade `@babel/core` to the required version: `npm install --save-dev @babel/core@^7.23.0` or `yarn add -D @babel/core@^7.23.0`.
```
Requires TypeScript '^5.3.0'
```
cause Your installed `typescript` version does not meet the peer dependency requirement of `babel-preset-proposal-typescript@4.0.0`.

fix Upgrade `typescript` to the required version: `npm install --save-dev typescript@^5.3.0` or `yarn add -D typescript@^5.3.0`.
```
Error: .babelrc configuration is invalid. presets[2] must be a string
```
cause Incorrect format for the preset entry in `.babelrc` or `babel.config.js`.

fix Ensure the preset is listed as a simple string `"babel-preset-proposal-typescript"` or an array `["babel-preset-proposal-typescript", { /* options */ }]` if you need to pass options.

Warnings

breaking Version 4.0.0 requires `@babel/core@^7.23.0` and `typescript@^5.3.0`. Users on older versions of Babel or TypeScript will need to upgrade their peer dependencies.
Fix: Ensure `@babel/core` is `^7.23.0` or higher and `typescript` is `^5.3.0` or higher in your `package.json` peer dependencies. Then run `npm install` or `yarn install`.
breaking Version 3.0.0 upgraded the minimum `typescript` peer dependency to `v4.7` and removed some internal plugins. This might cause compatibility issues for projects still using older TypeScript versions.
Fix: Upgrade your `typescript` dependency to `^4.7.0` or later. Review your Babel configuration as some previously managed plugins might now be handled natively by TypeScript or are no longer needed.
breaking Version 2.0.0 introduced breaking changes by bumping both Babel and TypeScript minimum versions and adding new proposals. Specific details might vary, but expect potential configuration and dependency conflicts.
Fix: Consult the changelog for `v2.0.0` to identify specific plugin changes or removals. Upgrade your Babel and TypeScript peer dependencies to meet the new requirements.
gotcha Since `v1.5.0`, `nullish-coalescing-operator` and `optional-chaining` transformations were dropped as TypeScript 3.7.0 introduced native support for these features. Relying on this preset for these specific transformations will no longer work.
Fix: For `nullish-coalescing-operator` and `optional-chaining`, ensure your project uses TypeScript 3.7.0 or newer and that `@babel/preset-typescript` (or similar) is configured to handle modern TypeScript syntax. This preset is strictly for proposals TypeScript *does not* yet support.
gotcha This preset only transforms proposals which TypeScript does not *currently* support. As TypeScript evolves and adopts new ECMAScript proposals, this preset may remove plugins for those features. This could lead to unexpected behavior if your build relies on the preset transforming a feature that TypeScript has since adopted.
Fix: Regularly review the changelog for this preset and the TypeScript release notes. Ensure your Babel configuration remains lean, relying on `@babel/preset-typescript` for standard TypeScript features and this preset only for the explicitly unsupported proposals.

Install

npm install babel-preset-proposal-typescript npm
yarn add babel-preset-proposal-typescript yarn
pnpm add babel-preset-proposal-typescript pnpm

Imports

Babel Preset Configuration
wrong:
```
import preset from 'babel-preset-proposal-typescript';
```
correct:
```
{ "presets": ["babel-preset-proposal-typescript"] }
```
This package is a Babel preset and is not imported directly into JavaScript/TypeScript files. It is configured within your Babel configuration file (e.g., `.babelrc.json` or `babel.config.js`) as an entry in the `presets` array.
Babel Node API Usage
wrong:
```
import { PresetName } from 'babel-preset-proposal-typescript';
```
correct:
```
require('babel-preset-proposal-typescript')
```
When using the Babel Node API, you might dynamically load presets. Use `require()` to obtain the preset function, which is then passed to Babel's transform functions, typically as part of a configuration object.

Quickstart

Demonstrates how to configure Babel with `babel-preset-proposal-typescript` to compile TypeScript code utilizing experimental ECMAScript proposals like `do expressions`, `record and tuple`, and `pipeline operator`.

{
  "plugins": [
    // Ensure decorators are enabled if you use them, and are correctly configured.
    // Babel's order matters: proposals before official features.
  ],
  "presets": [
    ["@babel/preset-env", { "targets": { "node": "current" } }],
    "@babel/preset-typescript",
    "babel-preset-proposal-typescript"
  ]
}
// Example index.ts
async function runDoExpression() {
  const result = await do {
    let x = 10;
    if (x > 5) {
      await Promise.resolve(x * 2);
    } else {
      x * 3;
    }
  };
  console.log('Do expression result:', result);
}

runDoExpression();

const tuple: [string, number] = #['hello', 123];
console.log('Tuple element:', tuple[0]);

function pipelineExample(value: number) {
  return value
    |> ((x) => x * 2)
    |> ((x) => x + 1);
}
console.log('Pipeline result:', pipelineExample(5));

// package.json script
// "scripts": {
//   "build": "babel src/index.ts --out-dir dist --extensions \".ts\""
// }

view raw JSON →