{"id":10549,"library":"babel-plugin-transform-typescript","title":"Babel Plugin for TypeScript Transformation","description":"This package, `@babel/plugin-transform-typescript`, is a core Babel plugin designed to strip TypeScript type annotations from code, transforming it into standard ECMAScript. It operates solely on the syntax level and does not perform any type-checking; users must integrate the TypeScript compiler (tsc) separately for type validation. The current stable major version is 7 (e.g., v7.29.2 as of March 2026), with active development ongoing for Babel 8, which is currently in release candidate stages (e.g., v8.0.0-rc.3). Babel maintains a frequent release cadence for patch versions and rolls out minor/major updates periodically. A key differentiator is its focus on pure syntax transformation, which makes it faster than a full TypeScript compilation but also means it explicitly does not support TypeScript-specific features like `namespace` declarations, `const enum`s, or the legacy `export =` and `import =` syntax, as these features require type information for meaningful transformation.","status":"active","version":"7.0.0-alpha.19","language":"javascript","source_language":"en","source_url":"https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-typescript","tags":["javascript","babel-plugin","typescript"],"install":[{"cmd":"npm install babel-plugin-transform-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-transform-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-transform-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the core Babel transpiler to execute the plugin.","package":"@babel/core","optional":false}],"imports":[{"note":"This is the standard way to include the plugin in `.babelrc.json` or `babel.config.json`. The plugin itself is implicitly loaded by Babel.","wrong":"{\n  \"plugins\": [\n    \"babel-plugin-transform-typescript\" // Older, unscoped name\n  ]\n}","symbol":"Config via plugins array","correct":"{\n  \"plugins\": [\n    \"@babel/plugin-transform-typescript\"\n  ]\n}"},{"note":"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.","wrong":"import { plugin } from '@babel/plugin-transform-typescript';","symbol":"Programmatic usage","correct":"const transform = require('@babel/core').transformSync;\nconst plugin = require('@babel/plugin-transform-typescript');\n\nconst code = `const x: number = 0;`;\nconst output = transform(code, {\n  plugins: [plugin]\n}).code;"},{"note":"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.","wrong":"babel --plugins transform-typescript src/index.ts","symbol":"CLI usage","correct":"babel --plugins @babel/plugin-transform-typescript src/index.ts --out-file dist/index.js"}],"quickstart":{"code":"/* file: package.json */\n{\n  \"name\": \"my-ts-project\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"build\": \"babel src --out-dir dist --extensions \\\".ts,.tsx\\\"\"\n  },\n  \"devDependencies\": {\n    \"@babel/cli\": \"^7.0.0\",\n    \"@babel/core\": \"^7.0.0\",\n    \"@babel/plugin-transform-typescript\": \"^7.0.0\"\n  }\n}\n\n/* file: babel.config.js */\nmodule.exports = {\n  plugins: [\n    \"@babel/plugin-transform-typescript\",\n    // If you use React and JSX, also add:\n    // \"@babel/plugin-transform-react-jsx\"\n  ]\n};\n\n/* file: src/index.ts */\ninterface User {\n  id: number;\n  name: string;\n  email?: string;\n}\n\nconst user: User = {\n  id: 1,\n  name: \"Alice\",\n  email: \"alice@example.com\"\n};\n\nfunction greet(person: User): string {\n  return `Hello, ${person.name}! Your ID is ${person.id}.`;\n}\n\nconsole.log(greet(user));\n\n// Example of a type-only import (will be stripped by Babel)\nimport type { UtilityType } from './types';\n\n// A type declaration\ntype UtilityType = { timestamp: number };\nconst data: UtilityType = { timestamp: Date.now() };\nconsole.log(`Current data timestamp: ${data.timestamp}`);\n\n/* To run this example: */\n/* 1. Create the files above */\n/* 2. `npm install` */\n/* 3. `npm run build` */\n/* 4. `node dist/index.js` */","lang":"typescript","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=8.0.0-beta.4"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=8.0.0-beta.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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']`).","cause":"The plugin package is not installed or incorrectly referenced in the Babel configuration.","error":"Error: Cannot find plugin '@babel/plugin-transform-typescript'. Make sure you have installed it properly and are passing it a valid path."},{"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.","cause":"This is a TypeScript type error, which Babel does not catch because it only strips types and does not perform type checking.","error":"TS2345: Argument of type 'number' is not assignable to parameter of type 'string'."},{"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.","cause":"Attempting to use TypeScript features explicitly unsupported by `@babel/plugin-transform-typescript`.","error":"SyntaxError: 'namespace' is not supported by Babel or 'const enum' is not supported by Babel"}],"ecosystem":"npm"}