{"id":10545,"library":"babel-plugin-syntax-typescript","title":"Babel Plugin: Syntax TypeScript","description":"@babel/plugin-syntax-typescript is a core Babel plugin that enables Babel's parser to understand and parse TypeScript syntax without performing any transformations or type-checking. This plugin is essential for any Babel setup that needs to process TypeScript files, acting as the foundational layer for interpreting TypeScript-specific language features like type annotations, interfaces, and enums. It is typically used in conjunction with `@babel/plugin-transform-typescript` (or `@babel/preset-typescript`) for removing type annotations and transforming TypeScript code into standard JavaScript. The package is part of the actively developed Babel ecosystem, with `v7.29.2` being a recent stable release and `v8.0.0-rc.3` representing the upcoming major version, which includes significant breaking changes. Babel's release cadence is frequent, providing regular updates and security patches across both major versions. Key differentiators include its role in a highly configurable JavaScript transpilation pipeline and its ability to integrate with existing build tools, offering a performance advantage over `tsc` for pure transpilation by skipping type-checking.","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-syntax-typescript","tags":["javascript","babel-plugin","typescript"],"install":[{"cmd":"npm install babel-plugin-syntax-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-syntax-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-syntax-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Babel to process files and apply plugins.","package":"@babel/core","optional":false}],"imports":[{"note":"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.","wrong":"{ \"plugins\": [\"syntax-typescript\"] }","symbol":"Config via .babelrc","correct":"{ \"plugins\": [\"@babel/plugin-syntax-typescript\"] }"},{"note":"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.","wrong":"require('babel-core').transform(\"code\", { plugins: [\"syntax-typescript\"] });","symbol":"Node API (transformSync)","correct":"import { transformSync } from '@babel/core';\n\nconst code = `const x: string = 'hello';`;\nconst output = transformSync(code, {\n  plugins: ['@babel/plugin-syntax-typescript'],\n  filename: 'input.ts' // Important for Babel to infer syntax\n});\nconsole.log(output.code);"},{"note":"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.","wrong":"plugins: ['@babel/plugin-syntax-typescript', '@babel/plugin-transform-typescript']","symbol":"Combining with preset-typescript","correct":"import { transformSync } from '@babel/core';\n\nconst code = `interface MyInterface { name: string; }\nconst x: MyInterface = { name: 'world' };`;\nconst output = transformSync(code, {\n  presets: ['@babel/preset-typescript'],\n  filename: 'input.ts'\n});\nconsole.log(output.code); // Should output 'const x = { name: 'world' };'"}],"quickstart":{"code":"import { transformSync } from '@babel/core';\n\n// Example TypeScript code with type annotations\nconst tsCode = `\ninterface User {\n  id: number;\n  name: string;\n}\n\nfunction greetUser(user: User): string {\n  return `Hello, ${user.name}! Your ID is ${user.id}.`;\n}\n\nconst currentUser: User = { id: 123, name: 'Alice' };\nconsole.log(greetUser(currentUser));\n`;\n\n// The plugin-syntax-typescript *only* allows parsing, not transformation (type removal)\n// To transform (remove types), we usually use @babel/preset-typescript\ntry {\n  const parsedOnly = transformSync(tsCode, {\n    // Using the syntax plugin directly requires 'isTSX' or 'dts' options for context\n    // For simple TS parsing, it works, but doesn't remove types.\n    plugins: [['@babel/plugin-syntax-typescript', { isTSX: false, dts: false }]],\n    filename: 'input.ts' // Crucial for Babel to correctly interpret .ts files\n  });\n  console.log('--- Parsed Only (types still present in AST, but not transformed) ---');\n  console.log(parsedOnly.code);\n\n  // To actually remove types and transpile to plain JavaScript\n  const transformedCode = transformSync(tsCode, {\n    presets: ['@babel/preset-typescript'], // This preset includes both syntax and transform plugins\n    filename: 'input.ts'\n  });\n  console.log('\\n--- Transformed (types removed) ---');\n  console.log(transformedCode.code);\n} catch (error) {\n  console.error('Babel transformation failed:', error);\n}","lang":"typescript","description":"Demonstrates how to use `@babel/plugin-syntax-typescript` for parsing TypeScript code and contrasts it with `@babel/preset-typescript` for full transformation (type stripping)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=8.0.0-beta.4"},{"fix":"For synchronous operations, explicitly use `transformSync` from `@babel/core`. For asynchronous operations, ensure you're using `await transform(...)` or providing a callback.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"If you intend to transpile TypeScript, use `@babel/preset-typescript` in your Babel configuration. This preset includes both the syntax and transform plugins.","message":"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`.","severity":"gotcha","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Babel is attempting to parse TypeScript syntax without the necessary plugin enabled.","error":"Error: Parsing error: Unexpected token"},{"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.","cause":"Attempting to use CommonJS `require()` in an ESM context, typically when importing Babel 7's core or plugins in an ESM project.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}