Babel TypeScript Preset

Common errors

• SyntaxError: Cannot find preset 'typescript' relative to file

  cause The `@babel/preset-typescript` package is not installed or incorrectly referenced in your Babel configuration.
  fix Run `npm install --save-dev @babel/preset-typescript` or `yarn add --dev @babel/preset-typescript`. In your `.babelrc.json` or `babel.config.js`, ensure the preset is listed as `"@babel/preset-typescript"` or `['@babel/preset-typescript', {...}]`.

• SyntaxError: Private field '#myField' must be declared in an enclosing class

  cause Babel presets like `babel-preset-typescript` handle specific syntax. Modern JavaScript features (like private class fields, optional chaining, nullish coalescing) require `babel-preset-env` or specific plugins.
  fix Install `@babel/preset-env` (`npm install --save-dev @babel/preset-env`) and include it in your Babel configuration, typically after `babel-preset-typescript`. Example: `presets: [['@babel/preset-typescript'], ['@babel/preset-env', { targets: { node: 'current' }}]]`.

• ReferenceError: require is not defined in ES module scope

  cause You are attempting to use `require()` in an ES module environment, potentially within a `babel.config.js` or another configuration file that is treated as ESM.
  fix If your `babel.config.js` or similar file is in an ES module context, use `import` statements instead of `require()`. For Babel presets, this might look like `import presetTypescript from '@babel/preset-typescript'; export default { presets: [presetTypescript] };`.

Warnings

• gotcha Babel's TypeScript preset only strips type annotations; it does not perform type checking. This means your code will transpile even if it contains type errors.
  Fix: Integrate a separate type-checking step into your build process using the TypeScript compiler (`tsc --noEmit`) to ensure type safety.
• breaking Starting with Babel 8, support for the legacy TypeScript `module <identifier>` syntax (internal modules/namespaces) has been dropped.
  Fix: Migrate away from `module <identifier>` declarations to standard ES module imports/exports or the `namespace` keyword if appropriate for your use case.
• gotcha `@babel/preset-typescript` must typically be listed before `@babel/preset-env` (or other syntax-transforming presets) in your Babel configuration `presets` array.
  Fix: Ensure the order in your `presets` array is `['@babel/preset-typescript', ...otherPresets]` so that TypeScript syntax is stripped before other transformations occur.

Install

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

Imports

• typescript (in .babelrc.json)
  wrong:

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

  correct:

  {
    "presets": [
      "@babel/preset-typescript"
    ]
  }

  Presets are configured under the `presets` key, not `plugins`. Prefer the full package name `@babel/preset-typescript` for clarity over the shorthand `typescript`.
• @babel/preset-typescript (in babel.config.js)
  wrong:

  // babel.config.js
  module.exports = {
    presets: [
      '@babel/preset-typescript' // No array for options or just 'typescript'
    ]
  };

  correct:

  // babel.config.js
  module.exports = {
    presets: [
      ['@babel/preset-typescript', {
        // options for the preset
        is='value'
      }]
    ]
  };

  When using `babel.config.js`, it's best practice to use an array for each preset, allowing for inline options. This also ensures correct resolution.
• transformAsync (Node API)
  wrong:

  const babel = require('babel-core'); // Deprecated package
  babel.transform(code, { presets: ['typescript'] });

  correct:

  import * as babel from '@babel/core';
  
  const code = `const x: number = 42;`;
  const result = await babel.transformAsync(code, {
    filename: 'input.ts', // Important for preset to recognize TS
    presets: [
      ['@babel/preset-typescript', { allowDeclareFields: true }],
      ['@babel/preset-env', { targets: { node: 'current' } }]
    ]
  });
  console.log(result?.code);

  The `babel-core` package is deprecated; use `@babel/core`. Always include `filename` when using the Node API to help Babel resolve presets correctly based on file extension. Also, pass presets as arrays with options.

Quickstart

This quickstart demonstrates how to use `@babel/preset-typescript` with `@babel/core` to strip TypeScript syntax and transpile to JavaScript, showing a simple class and type annotation.

import * as babel from '@babel/core';

const typescriptCode = `
interface Shape { 
  area(): number;
}

class Circle implements Shape {
  constructor(public radius: number) {}
  area(): number {
    return Math.PI * this.radius * this.radius;
  }
}

const myCircle: Circle = new Circle(10);
console.log('Circle area:', myCircle.area());

const greeting: string = 'Hello Babel!';
console.log(greeting);
`;

async function transformTsCode() {
  try {
    const result = await babel.transformAsync(typescriptCode, {
      filename: 'example.ts', // Essential for Babel to correctly apply TS preset
      presets: [
        ['@babel/preset-typescript', {
          // Example option: allows properties of classes to be declared without an initializer
          allowDeclareFields: true
        }],
        ['@babel/preset-env', {
          // Transpile for the current Node.js version
          targets: { node: 'current' }
        }]
      ]
    });

    console.log('--- Original TypeScript Code ---\n', typescriptCode);
    console.log('\n--- Transformed JavaScript Code (via Babel) ---\n', result?.code);
  } catch (error) {
    console.error('Babel transformation failed:', error);
  }
}

transformTsCode();