@babel/plugin-syntax-typescript

@babel/plugin-syntax-typescript is a Babel syntax plugin that enables parsing of TypeScript syntax without performing type checking or compilation. It configures the Babel parser to recognize TypeScript language features including type annotations, interfaces, enums, generic syntax, and optional TSX support for React components.

Package Information

• Package Name: @babel/plugin-syntax-typescript
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-syntax-typescript

Core Imports

The plugin is not directly imported in application code, but configured in Babel configuration files:

// Babel configuration (babel.config.js or .babelrc)
module.exports = {
  plugins: ["@babel/plugin-syntax-typescript"]
};

With options:

module.exports = {
  plugins: [
    ["@babel/plugin-syntax-typescript", {
      disallowAmbiguousJSXLike: true,
      dts: true
    }]
  ]
};

For programmatic usage (advanced):

import syntaxTypescript from "@babel/plugin-syntax-typescript";
import { transform } from "@babel/core";

const result = transform(code, {
  plugins: [[syntaxTypescript, { dts: true }]]
});

Basic Usage

The plugin is primarily used through Babel configuration files. It automatically enables TypeScript syntax parsing for any JavaScript files processed by Babel.

// babel.config.js
module.exports = {
  plugins: ["@babel/plugin-syntax-typescript"],
  presets: ["@babel/preset-env"]
};

For TSX files (TypeScript + JSX):

// babel.config.js (Babel 7 only)
module.exports = {
  plugins: [
    ["@babel/plugin-syntax-typescript", { isTSX: true }]
  ]
};

Capabilities

Plugin Factory Function

The main export is a Babel plugin factory function that returns a configured plugin object.

/**
 * Babel plugin for TypeScript syntax parsing
 * This is the default export created via declare() from @babel/helper-plugin-utils
 */
declare const syntaxTypescriptPlugin: (
  api: PluginAPI,
  opts: Options,
  dirname: string
) => PluginObject;

export default syntaxTypescriptPlugin;

interface PluginAPI {
  /** Assert that the current Babel version meets the minimum requirement */
  assertVersion(range: number | string): void;
  version: string;
}

/**
 * Global function for specifying required Babel versions in plugins
 * Automatically configured by Babel build system
 */
declare function REQUIRED_VERSION(version: number): number | string;
declare function REQUIRED_VERSION(version: string): string;

Configuration Options

Plugin configuration interface for customizing TypeScript parsing behavior.

export interface Options {
  /** 
   * Disallow ambiguous JSX-like syntax that could be confused between 
   * type assertions and JSX elements (e.g., `<foo>bar</foo>`)
   * @default false
   */
  disallowAmbiguousJSXLike?: boolean;
  
  /** 
   * Enable parsing of TypeScript declaration (.d.ts) files
   * @default false
   */
  dts?: boolean;
  
  /** 
   * Enable JSX parsing for TSX files (Babel 7 only)
   * @default false
   * @deprecated Use file extensions or other plugins for TSX support in Babel 8+
   */
  isTSX?: boolean;
}

Plugin Object Structure

The plugin returns a standard Babel plugin object with parser manipulation capabilities.

interface PluginObject {
  /** Plugin identifier name */
  name: "syntax-typescript";
  
  /** 
   * Configures Babel parser options to enable TypeScript syntax parsing
   * Removes conflicting plugins (flow, jsx) and adds TypeScript parser plugin
   * @param opts - Babel compilation options object
   * @param parserOpts - Parser configuration object with plugins array
   */
  manipulateOptions(opts: any, parserOpts: { plugins: any[] }): void;
}

TypeScript Features Enabled

This plugin enables Babel to parse the following TypeScript syntax:

• Type Annotations: Variable, parameter, and return type annotations
• Interfaces: Interface declarations and implementations
• Type Aliases: Custom type definitions using type keyword
• Enums: Numeric and string enum declarations
• Generics: Generic type parameters and constraints
• Namespaces: Module and namespace declarations
• Type Assertions: Both <Type>value and value as Type syntax
• Optional Properties: Properties marked with ? operator
• Access Modifiers: public, private, protected keywords
• Abstract Classes: Abstract class and method declarations
• Decorators: When used with appropriate decorator plugins
• TSX Syntax: JSX with TypeScript when isTSX: true (Babel 7)

Error Handling

The plugin validates Babel version compatibility and throws descriptive errors for unsupported versions:

/**
 * Version compatibility error thrown by assertVersion
 */
interface BabelVersionError extends Error {
  code: "BABEL_VERSION_UNSUPPORTED";
  version: string;
  range: string;
}

• BABEL_VERSION_UNSUPPORTED: Thrown when Babel version is incompatible
• Parser Conflicts: Automatically resolves conflicts with Flow and JSX plugins
• Ambiguous Syntax: Can be configured to reject ambiguous JSX-like syntax

Version Compatibility

• Babel Version: Requires ^7.0.0-0 or later
• Node.js: >=6.9.0
• TypeScript: Compatible with TypeScript syntax (all versions)

Note: Babel 8 removes the isTSX option in favor of file-extension-based detection and dedicated TSX handling plugins.