Babel Plugin for TypeScript Transformation

Common errors

• Error: Cannot find plugin '@babel/plugin-transform-typescript'. Make sure you have installed it properly and are passing it a valid path.

  cause The plugin package is not installed or incorrectly referenced in the Babel configuration.
  fix Ensure `@babel/plugin-transform-typescript` is installed (`npm install --save-dev @babel/plugin-transform-typescript`) and correctly specified in your `babel.config.js` or `.babelrc` (e.g., `plugins: ['@babel/plugin-transform-typescript']`).

• TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

  cause This is a TypeScript type error, which Babel does not catch because it only strips types and does not perform type checking.
  fix Run `tsc --noEmit` as part of your build process or ensure your IDE/editor is configured to show TypeScript errors. Correct the type mismatch in your source code.

• SyntaxError: 'namespace' is not supported by Babel or 'const enum' is not supported by Babel

  cause Attempting to use TypeScript features explicitly unsupported by `@babel/plugin-transform-typescript`.
  fix Refactor your code to use ES Module `import`/`export` instead of `namespace`, and use standard `enum`s or plain JavaScript objects/literals instead of `const enum`s.

Warnings

• breaking When upgrading to Babel 8 (currently in release candidate), `@babel/plugin-transform-typescript` drops support for TypeScript's legacy `module <identifier>` syntax. This is part of a broader push to align with modern ES Modules.
  Fix: Migrate `module <identifier> { ... }` declarations to modern ES Modules using `import`/`export` syntax, or consider using TypeScript's `namespace` feature with appropriate Babel configuration if absolutely necessary (though `namespace` is generally discouraged in favor of ES Modules).
• gotcha This plugin *only* strips TypeScript type annotations; it does not perform type checking. Code that is syntactically valid but contains type errors will still be transpiled without error. You must run the TypeScript compiler (tsc) separately for full type validation.
  Fix: Integrate `tsc` into your build process to perform type checking. A common pattern is to use Babel for transpilation and `tsc` solely for type verification (e.g., `tsc --noEmit`).
• gotcha The plugin explicitly does not support certain TypeScript-specific features like `namespace` declarations, `const enum`s, or the legacy `export =` and `import =` syntax. These features require type information to transpile correctly, which Babel's type-stripping approach does not provide.
  Fix: Avoid using `namespace`, `const enum`, `export =`, and `import =`. Prefer modern ES Module `import`/`export` statements. For constant-like enums, consider regular `enum`s or plain objects/literals.
• breaking Upgrading to Babel 8 generally introduces several breaking changes across the Babel ecosystem, including changes in `babel-parser`, `@babel/code-frame`, and `@babel-eslint-parser`. While this plugin's specific API might remain stable, overall Babel configuration and integration may require significant updates.
  Fix: Review the full Babel 8 upgrade guide carefully. Test your entire build pipeline thoroughly when moving from Babel 7 to Babel 8. Pay attention to parser options, default behaviors, and deprecated features.

Install

• npm install babel-plugin-transform-typescript npm
• yarn add babel-plugin-transform-typescript yarn
• pnpm add babel-plugin-transform-typescript pnpm

Imports

• Config via plugins array
  wrong:

  {
    "plugins": [
      "babel-plugin-transform-typescript" // Older, unscoped name
    ]
  }

  correct:

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

  This is the standard way to include the plugin in `.babelrc.json` or `babel.config.json`. The plugin itself is implicitly loaded by Babel.
• Programmatic usage
  wrong:

  import { plugin } from '@babel/plugin-transform-typescript';

  correct:

  const transform = require('@babel/core').transformSync;
  const plugin = require('@babel/plugin-transform-typescript');
  
  const code = `const x: number = 0;`;
  const output = transform(code, {
    plugins: [plugin]
  }).code;

  The plugin is typically required directly as a CommonJS module for programmatic usage, not imported as an ESM module for direct execution in application code. It exports the plugin function as its default export.
• CLI usage
  wrong:

  babel --plugins transform-typescript src/index.ts

  correct:

  babel --plugins @babel/plugin-transform-typescript src/index.ts --out-file dist/index.js

  When using the Babel CLI, specify the full scoped package name for the plugin. The older unscoped name might work depending on your `node_modules` structure but is discouraged.

Quickstart

This quickstart demonstrates how to install and configure `@babel/plugin-transform-typescript` to transpile a TypeScript file containing interfaces, type-only imports, and functions into standard JavaScript using the Babel CLI.

/* file: package.json */
{
  "name": "my-ts-project",
  "version": "1.0.0",
  "scripts": {
    "build": "babel src --out-dir dist --extensions \".ts,.tsx\""
  },
  "devDependencies": {
    "@babel/cli": "^7.0.0",
    "@babel/core": "^7.0.0",
    "@babel/plugin-transform-typescript": "^7.0.0"
  }
}

/* file: babel.config.js */
module.exports = {
  plugins: [
    "@babel/plugin-transform-typescript",
    // If you use React and JSX, also add:
    // "@babel/plugin-transform-react-jsx"
  ]
};

/* file: src/index.ts */
interface User {
  id: number;
  name: string;
  email?: string;
}

const user: User = {
  id: 1,
  name: "Alice",
  email: "alice@example.com"
};

function greet(person: User): string {
  return `Hello, ${person.name}! Your ID is ${person.id}.`;
}

console.log(greet(user));

// Example of a type-only import (will be stripped by Babel)
import type { UtilityType } from './types';

// A type declaration
type UtilityType = { timestamp: number };
const data: UtilityType = { timestamp: Date.now() };
console.log(`Current data timestamp: ${data.timestamp}`);

/* To run this example: */
/* 1. Create the files above */
/* 2. `npm install` */
/* 3. `npm run build` */
/* 4. `node dist/index.js` */