@vue/eslint-config-typescript

@vue/eslint-config-typescript

ESLint configuration for Vue 3 + TypeScript projects.

See @typescript-eslint/eslint-plugin for available rules.

This config is designed for create-vue setups. Other projects can use it, but may need project-specific adjustments.

It may rely on other create-vue defaults, such as eslint-plugin-vue being extended in the same final config.

The current version doesn't support the legacy .eslintrc* configuration format. Use version 13 or earlier for that format. See the corresponding README for more usage instructions.

Installation

npm add --dev @vue/eslint-config-typescript

Please also make sure that you have typescript and eslint installed.

Usage

For new flat configs, use these two exports:

• withVueTs, a helper that builds a flat ESLint config for Vue.js + TypeScript. It accepts either withVueTs(...configs) or withVueTs(options, ...configs).
• vueTsConfigs, the shared configurations from typescript-eslint adapted for .vue files in addition to TypeScript files. The names are in camel case, such as vueTsConfigs.recommendedTypeChecked.

The helper APIs used before v14.9 remain available for existing projects. See Helper APIs Before v14.9.

Recommended

withVueTs(...) is available in v14.9 and later. Export the withVueTs(...) call from eslint.config.js, eslint.config.mjs, or eslint.config.ts.

// eslint.config.mjs
import pluginVue from 'eslint-plugin-vue'
import { withVueTs, vueTsConfigs } from '@vue/eslint-config-typescript'

export default withVueTs(
  pluginVue.configs['flat/essential'],
  vueTsConfigs.recommended,
)

The above configuration enables the essential rules for Vue 3 and the recommended rules for TypeScript.

All the <script> blocks in .vue files MUST be written in TypeScript (should be either <script setup lang="ts"> or <script lang="ts">).

withVueTs(...) accepts config objects, config arrays, and promises. This matches the input style used by eslint-flat-config-utils, so configs built with Antfu's or Nuxt's ESLint config utilities can be passed to withVueTs(...) for Vue + TypeScript resolution.

Linting with Type Information

Some typescript-eslint rules use type information to provide deeper insights into the project code. Type-checking is much slower than linting with syntax information only. Setting up typed linting for ESLint without severe performance penalties can be difficult.

We don't recommend configuring individual type-aware rules and the corresponding language options manually. Start with the recommendedTypeChecked configuration, then turn rules on or off as needed.

// eslint.config.mjs
import pluginVue from 'eslint-plugin-vue'
import { withVueTs, vueTsConfigs } from '@vue/eslint-config-typescript'

export default withVueTs(
  pluginVue.configs['flat/essential'],
  vueTsConfigs.recommendedTypeChecked,
)

Project Options

withVueTs(...) accepts options for this config as the first argument. These are the same options accepted by configureVueProject(...) in the helper APIs before v14.9.

Only pass the options that differ from the defaults. This example lists all available options:

// eslint.config.mjs
import pluginVue from 'eslint-plugin-vue'
import { withVueTs, vueTsConfigs } from '@vue/eslint-config-typescript'

export default withVueTs(
  {
    // Whether to parse TypeScript syntax in Vue templates.
    // Defaults to `true`.
    // Setting it to `false` could improve performance.
    // But TypeScript syntax in Vue templates will then lead to syntax errors.
    // Also, type-aware rules won't be applied to expressions in templates in that case.
    tsSyntaxInTemplates: true,

    // Specify the script langs in `.vue` files
    // Defaults to `['ts']`.
    scriptLangs: [
      'ts',

      // [!DISCOURAGED]
      // Include 'js' to allow plain `<script>` or `<script setup>` blocks.
      // This might result-in false positive or negatives in some rules for `.vue` files.
      // Note you also need to configure `allowJs: true` and `checkJs: true`
      // in corresponding `tsconfig.json` files.
      // 'js',

      // [!STRONGLY DISCOURAGED]
      // Include 'tsx' to allow `<script lang="tsx">` blocks.
      // This would be in conflict with all type-aware rules.
      // 'tsx',

      // [!STRONGLY DISCOURAGED]
      // Include 'jsx' to allow `<script lang="jsx">` blocks.
      // This would be in conflict with all type-aware rules and may result in false positives.
      // 'jsx',
    ],

    // Whether to override some `no-unsafe-*` rules to avoid false positives on Vue component operations.
    // Defaults to `true`.
    // Usually you should keep this enabled,
    // but if you're using a metaframework or in a TSX-only project
    // where you're certain you won't operate on `.vue` components in a way that violates the rules,
    // and you want the strictest rules (e.g. when extending from `strictTypeChecked`),
    // you can set this to `false` to ensure the strictest rules apply to all files.
    allowComponentTypeUnsafety: true,

    // The root directory to resolve the `.vue` files.
    // Defaults to `process.cwd()`.
    // More info: <https://github.com/vuejs/eslint-plugin-vue/issues/1910#issuecomment-1819993961>
    // You may need to set this to the root directory of your project if you have a monorepo.
    // This is useful when you allow any other languages than `ts` in `.vue` files.
    // Our config helper would resolve and parse all the `.vue` files under `rootDir`,
    // and only apply the loosened rules to the files that do need them.
    rootDir: import.meta.dirname,

    // Whether to include dot folders when resolving `.vue` files under `rootDir`.
    // Defaults to `false`.
    // You may need to set this to `true` if your project stores Vue components
    // under folders such as `.vitepress`.
    includeDotFolders: false,
  },
  pluginVue.configs['flat/essential'],
  vueTsConfigs.recommendedTypeChecked,
)

Helper APIs Before v14.9

Configs written before v14.9 usually use defineConfigWithVueTs(...) as the final config helper, with configureVueProject(...) for the same project options.

Both APIs remain supported. defineConfigWithVueTs(...) accepts flat config entries and applies the final Vue + TypeScript resolution. configureVueProject(...) sets the project options used by defineConfigWithVueTs(...).

The pre-v14.9 API shape:

configureVueProject(options)
export default defineConfigWithVueTs(...configs)

maps to:

export default withVueTs(options, ...configs)

// eslint.config.mjs
import pluginVue from 'eslint-plugin-vue'
import {
  defineConfigWithVueTs,
  vueTsConfigs,
  configureVueProject,
} from '@vue/eslint-config-typescript'

configureVueProject({
  rootDir: import.meta.dirname,
  scriptLangs: ['ts', 'js'],
})

export default defineConfigWithVueTs(
  pluginVue.configs['flat/essential'],
  vueTsConfigs.recommended,
)

Migration

To migrate an existing flat config from defineConfigWithVueTs(...) / configureVueProject(...) to withVueTs(...), use:

npx @vue/eslint-config-typescript migrate-to-with-vue-ts

This command is interactive by default. It discovers eslint.config.{js,mjs,ts,mts}, shows the planned changes, and asks before writing files.

The codemod is conservative. It auto-fixes common top-level helper patterns, and reports unusual cases such as non-top-level configureVueProject(...) calls or ambiguous first arguments for manual migration.

Explicit paths and non-interactive runs are also supported:

npx @vue/eslint-config-typescript migrate-to-with-vue-ts eslint.config.ts
npx @vue/eslint-config-typescript migrate-to-with-vue-ts "packages/*/eslint.config.ts" --yes

There is also a versioned alias:

npx @vue/eslint-config-typescript migrate-14.9

Use migrate-to-with-vue-ts as the primary interface. The alias is only a convenience for this specific migration and future releases may add other migrations.

Use As a Normal Shared ESLint Config (Not Recommended)

This package can be used as a normal ESLint config, without withVueTs or defineConfigWithVueTs. In that setup, overriding the rules for .vue files is more difficult and comes with many nuances. Use this mode with caution.

See the documentation for 14.1 and earlier versions for more information.

Further Reading

• All the extendable configurations from typescript-eslint.
• All the available rules from typescript-eslint.