Babel Preset for TypeScript Vue 3 SFCs

Common errors

• SyntaxError: Unexpected token ':' (or similar for TypeScript syntax errors)

  cause Vue SFC `<script lang='ts'>` content is being parsed by a JavaScript transpiler (e.g., `@babel/preset-env`) without prior TypeScript stripping, as `babel-preset-typescript-vue3` is missing or misconfigured.
  fix Confirm `babel-preset-typescript-vue3` is listed in your Babel `presets` array within your `babel.config.js` or `.babelrc`. Ensure it is placed before `@babel/preset-env` and `@babel/preset-typescript` to prioritize TypeScript transformation for Vue SFCs. Also verify `babel-loader` is correctly applied to `.vue` files.

• Error: You gave us a parser plugin that doesn't exist yet...

  cause This error typically indicates an outdated `@babel/core` or related `@babel/*` package, or an issue where the `babel-preset-typescript-vue3`'s internal plugins are not being loaded correctly due to an incompatible Babel environment.
  fix Update your `@babel/core` to meet the `babel-preset-typescript-vue3`'s peer dependency requirements (e.g., `^7.0.0-0`). Run `npm install` or `yarn install` to ensure all Babel dependencies are correctly resolved. Double-check your Babel configuration for any conflicting or old plugin declarations.

Warnings

• gotcha Without `babel-preset-typescript-vue3`, Vue 3 Single File Components (SFCs) using `<script lang='ts'>` may not be correctly processed by Babel, leading to syntax errors or unexpected behavior. The standard `@babel/preset-typescript` historically ignores `.vue` files due to filename assumptions, causing transpilation failures for TypeScript within SFCs.
  Fix: Ensure `'babel-preset-typescript-vue3'` is included in your Babel `presets` array in `babel.config.js` or `.babelrc`. It should typically be placed before `@babel/preset-typescript` to ensure `.vue` files are handled correctly. Also, verify your `babel-loader` rule in Webpack covers `.vue` files.
• deprecated The package documentation suggests that this preset might become unnecessary in the future if `vue-loader` natively integrates Babel transpilation for TypeScript SFCs. Developers should be aware of this potential for future deprecation.
  Fix: Regularly monitor official `vue-loader` and Vue.js documentation and release notes for updates regarding native TypeScript SFC transpilation with Babel. Be prepared to remove or replace this preset if its functionality is absorbed into core tooling.
• gotcha Ensure all Babel-related dependencies, especially `@babel/core` and `@vue/compiler-sfc`, are compatible with the specific version of `babel-preset-typescript-vue3` you are using. Incompatibilities can lead to cryptic errors or unexpected transpilation issues, particularly after major dependency updates.
  Fix: Consult the `package.json` for this preset's peer dependencies and review its changelog for specific version requirements of Babel and Vue.js. Use `npm outdated` or `yarn upgrade` to manage your project's dependencies and keep them aligned.

Install

• npm install babel-preset-typescript-vue3 npm
• yarn add babel-preset-typescript-vue3 yarn
• pnpm add babel-preset-typescript-vue3 pnpm

Imports

• babel-preset-typescript-vue3

  presets: ['babel-preset-typescript-vue3']

  The preset is referenced by its string name within your Babel configuration file (e.g., `babel.config.js` or `.babelrc`).
• Preset Options

  presets: [['babel-preset-typescript-vue3', { /* options */ }]]

  To pass options to the preset, wrap the preset name and an options object in an array. All options for this preset match those of `@babel/preset-typescript`.
• Babel Config (ESM)
  wrong:

  module.exports = { presets: [...] };

  correct:

  export default { presets: [...] };

  Modern Babel configurations often leverage ESM syntax for `babel.config.js`. While `module.exports` still works for CommonJS projects, `export default` is the preferred style for new setups.

Quickstart

Demonstrates how to integrate `babel-preset-typescript-vue3` within a Webpack configuration to correctly transpile Vue 3 SFCs with TypeScript, alongside `@babel/preset-env` and `@babel/preset-typescript`.

module.exports = {
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: "vue-loader"
      },
      {
        test: /\.(j|t)sx?$/,
        exclude: /node_modules/,
        use: {
          loader: "babel-loader",
          options: {
            presets: [
              "@babel/preset-env",
              "babel-preset-typescript-vue3",
              "@babel/preset-typescript"
            ]
          }
        }
      }
    ]
  }
};