Babel Plugin: Syntax TypeScript

Common errors

• Error: Parsing error: Unexpected token

  cause Babel is attempting to parse TypeScript syntax without the necessary plugin enabled.
  fix Ensure `@babel/plugin-syntax-typescript` (or `@babel/preset-typescript`) is correctly added to your Babel plugins/presets configuration, and that Babel is processing `.ts` or `.tsx` files. Also, specify `filename` if using Node API.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` in an ESM context, typically when importing Babel 7's core or plugins in an ESM project.
  fix For Babel 7+, use ES module `import` syntax (`import { transformSync } from '@babel/core';`) when working in an ES module environment. Babel 8 is ESM-first.

Warnings

• breaking Babel 8 drops support for TypeScript's legacy `module <identifier>` syntax. This specifically impacts users relying on internal (namespace-like) modules or older ambient module declarations in TypeScript.
  Fix: Migrate `module X {}` declarations to ES module imports/exports or `namespace X {}` for type-only declarations. Update ambient modules from `declare module 'foo' { module 'bar' {} }` to `declare module 'foo/bar' {}` or similar ES module-compatible patterns.
• breaking In Babel 8, the `transform` function in `@babel/core` will become purely asynchronous. The synchronous behavior in Babel 7 for calls without a callback will be removed.
  Fix: For synchronous operations, explicitly use `transformSync` from `@babel/core`. For asynchronous operations, ensure you're using `await transform(...)` or providing a callback.
• gotcha This plugin (`@babel/plugin-syntax-typescript`) *only* enables parsing of TypeScript syntax. It does *not* remove type annotations or transpile TypeScript to JavaScript. For full transformation, you must also use `@babel/plugin-transform-typescript` or, more commonly, `@babel/preset-typescript`.
  Fix: If you intend to transpile TypeScript, use `@babel/preset-typescript` in your Babel configuration. This preset includes both the syntax and transform plugins.
• gotcha Babel does not perform type-checking. Even with `@babel/preset-typescript`, your TypeScript code will be transpiled to JavaScript without validating its types. This can lead to runtime errors that a full TypeScript compiler (`tsc`) would catch.
  Fix: Integrate `tsc` into your build pipeline alongside Babel for comprehensive type-checking. A common pattern is to use Babel for fast transpilation and `tsc` for type verification and `.d.ts` generation.

Install

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

Imports

• Config via .babelrc
  wrong:

  { "plugins": ["syntax-typescript"] }

  correct:

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

  For Babel 7+, scope packages with `@babel/` prefix. The short name 'syntax-typescript' works but is less explicit and might cause issues in complex configs or older Babel versions.
• Node API (transformSync)
  wrong:

  require('babel-core').transform("code", { plugins: ["syntax-typescript"] });

  correct:

  import { transformSync } from '@babel/core';
  
  const code = `const x: string = 'hello';`;
  const output = transformSync(code, {
    plugins: ['@babel/plugin-syntax-typescript'],
    filename: 'input.ts' // Important for Babel to infer syntax
  });
  console.log(output.code);

  Since Babel 7, `@babel/core` is the recommended package. `transformSync` is preferred for synchronous operations, and `transform` now defaults to async. The `filename` option is crucial for Babel to correctly apply syntax plugins for `.ts` files.
• Combining with preset-typescript
  wrong:

  plugins: ['@babel/plugin-syntax-typescript', '@babel/plugin-transform-typescript']

  correct:

  import { transformSync } from '@babel/core';
  
  const code = `interface MyInterface { name: string; }
  const x: MyInterface = { name: 'world' };`;
  const output = transformSync(code, {
    presets: ['@babel/preset-typescript'],
    filename: 'input.ts'
  });
  console.log(output.code); // Should output 'const x = { name: 'world' };'

  Using `@babel/preset-typescript` is generally preferred as it includes both `syntax-typescript` (for parsing) and `transform-typescript` (for stripping types) and handles file extensions automatically. Specifying both separately is redundant and can lead to issues.

Quickstart

Demonstrates how to use `@babel/plugin-syntax-typescript` for parsing TypeScript code and contrasts it with `@babel/preset-typescript` for full transformation (type stripping).

import { transformSync } from '@babel/core';

// Example TypeScript code with type annotations
const tsCode = `
interface User {
  id: number;
  name: string;
}

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

const currentUser: User = { id: 123, name: 'Alice' };
console.log(greetUser(currentUser));
`;

// The plugin-syntax-typescript *only* allows parsing, not transformation (type removal)
// To transform (remove types), we usually use @babel/preset-typescript
try {
  const parsedOnly = transformSync(tsCode, {
    // Using the syntax plugin directly requires 'isTSX' or 'dts' options for context
    // For simple TS parsing, it works, but doesn't remove types.
    plugins: [['@babel/plugin-syntax-typescript', { isTSX: false, dts: false }]],
    filename: 'input.ts' // Crucial for Babel to correctly interpret .ts files
  });
  console.log('--- Parsed Only (types still present in AST, but not transformed) ---');
  console.log(parsedOnly.code);

  // To actually remove types and transpile to plain JavaScript
  const transformedCode = transformSync(tsCode, {
    presets: ['@babel/preset-typescript'], // This preset includes both syntax and transform plugins
    filename: 'input.ts'
  });
  console.log('\n--- Transformed (types removed) ---');
  console.log(transformedCode.code);
} catch (error) {
  console.error('Babel transformation failed:', error);
}