Skip to content

Vue Compiler Options

Jump to bottom
Johnson Chu edited this page Jan 31, 2026 · 24 revisions

This document provides a comprehensive guide to the vueCompilerOptions available in Vue Language Tools. These options allow you to fine-tune the behavior of the Vue language server and vue-tsc.

Configuration

You can configure these options in two ways:

  1. Global Configuration (tsconfig.json): Add a vueCompilerOptions key to your tsconfig.json or jsconfig.json.

    {
  "compilerOptions": {
    // ...
  },
  "vueCompilerOptions": {
    "strictTemplates": true,
    "target": 3.3
  }
}

  2. Per-File Configuration v2.2.0: Use special comments at the top of a .vue file to override global settings for that file.

    <!-- @vue-strict-templates true -->
<!-- @vue-target 3.3 -->

<script setup>
// ...
</script>

Options Reference

Core

target

  • Type: number
  • Default: Automatically detected from the installed vue version, otherwise 3.3.

Specifies the target Vue version for the compiler. This affects how templates are compiled and what features are available.

Example:

Setting the target to 2.7 enables Vue 2-specific behaviors.

{
  "vueCompilerOptions": {
    "target": 2.7
  }
}

lib

  • Type: string
  • Default: "vue"

Specifies the package name for Vue's runtime. This is useful if you are using a fork of Vue or a custom package name.

Example:

If you are using a custom Vue library named my-vue-fork.

{
  "vueCompilerOptions": {
    "lib": "my-vue-fork"
  }
}

typesRoot v3.2.0

  • Type: string
  • Default: "@vue/language-core/types"

Specifies the path to the Vue Language Tools type definitions. This is typically not needed unless you have a custom setup.

Example:

To use a custom types root.

{
  "vueCompilerOptions": {
    "typesRoot": "./node_modules/@vue/language-core/types"
  }
}

File Handling

extensions

  • Type: string[]
  • Default: [".vue"]

An array of file extensions that should be treated as Vue components.

Example:

To treat .story files as Vue components.

{
  "vueCompilerOptions": {
    "extensions": [".vue", ".story"]
  }
}

vitePressExtensions v2.0.15

  • Type: string[]
  • Default: []

An array of file extensions that should be treated as VitePress markdown files. The content will be parsed as Vue components embedded in Markdown.

Example:

To enable VitePress support for .md files.

{
  "vueCompilerOptions": {
    "vitePressExtensions": [".md"]
  }
}

petiteVueExtensions v2.0.15

  • Type: string[]
  • Default: []

An array of file extensions that should be treated as Petite Vue files. The content will be parsed as HTML with Vue directives.

Example:

To enable Petite Vue support for .html files.

{
  "vueCompilerOptions": {
    "petiteVueExtensions": [".html"]
  }
}

Strictness

strictTemplates

  • Type: boolean
  • Default: false

A master switch for enabling all strict-checking options. When true, it enables strictVModel, checkUnknownProps, checkUnknownEvents, checkUnknownDirectives, and checkUnknownComponents.

Example:

{
  "vueCompilerOptions": {
    "strictTemplates": true
  }
}

strictVModel v3.0.0

  • Type: boolean
  • Default: false (or the value of strictTemplates if set)

Enforces strict type checking for v-model bindings.

Example:

When true, this will flag an error if you try to bind v-model to a prop that is not a valid model value.

<script setup lang="ts">
const model = defineModel<string>();
</script>

<template>
  <!-- Error if model is not a number -->
  <input v-model.number="model" />
</template>

strictCssModules v3.0.0

  • Type: boolean
  • Default: false

Enforces strict type checking for CSS modules. When true, accessing a non-existent class from a CSS module will result in a type error.

Example:

<style module>
.myClass {}
</style>

<template>
  <!-- Error: Property 'nonExistent' does not exist on type... -->
  <div :class="$style.nonExistent"></div>
</template>

checkUnknownProps v2.2.2

  • Type: boolean
  • Default: false (or the value of strictTemplates if set)

Warns about passing props to a component that are not explicitly defined in its defineProps.

Example:

<!-- MyComponent.vue -->
<script setup lang="ts">
defineProps<{ title: string }>();
</script>

<!-- App.vue -->
<!-- Error: Property 'description' does not exist on type... -->
<MyComponent title="Hello" description="World" />

checkUnknownEvents v2.2.2

  • Type: boolean
  • Default: false (or the value of strictTemplates if set)

Warns about listening to events that are not explicitly defined in a component's defineEmits.

Example:

<!-- MyComponent.vue -->
<script setup lang="ts">
defineEmits<{ (e: 'change'): void }>();
</script>

<!-- App.vue -->
<!-- Error: Event 'update' is not defined on component... -->
<MyComponent @change="() => {}" @update="() => {}" />

checkUnknownDirectives v2.2.2

  • Type: boolean
  • Default: false (or the value of strictTemplates if set)

Warns about using custom directives that are not globally or locally registered.

Example:

<!-- Error: Unknown directive 'my-directive' -->
<div v-my-directive></div>

checkUnknownComponents v2.2.2

  • Type: boolean
  • Default: false (or the value of strictTemplates if set)

Warns about using components that are not imported and registered.

Example:

<template>
  <!-- Error: The component 'MyComponent' is not registered. -->
  <MyComponent />
</template>

Type Inference

inferComponentDollarEl v2.2.4

  • Type: boolean
  • Default: false

Infers the type of the component's root element for $el.

Example:

When true, this.$el will be typed as HTMLDivElement | undefined.

<script lang="ts">
import { defineComponent } from 'vue';
export default defineComponent({
  mounted() {
    // this.$el is typed as HTMLDivElement
    this.$el.focus();
  }
});
</script>

<template>
  <div>...</div>
</template>

inferComponentDollarRefs v2.2.4

  • Type: boolean
  • Default: false

Infers the types of template refs for $refs.

Example:

When true, this.$refs.myInput will be typed as HTMLInputElement | undefined.

<script lang="ts">
import { defineComponent } from 'vue';
export default defineComponent({
  mounted() {
    // this.$refs.myInput is typed as HTMLInputElement
    (this.$refs.myInput as HTMLInputElement).focus();
  }
});
</script>

<template>
  <input ref="myInput" />
</template>

inferTemplateDollarAttrs v2.2.4

  • Type: boolean
  • Default: false

Infers the type of $attrs in the template and for useAttrs().

Example:

When true, $attrs will have proper types, allowing for autocompletion and type checking.

<template>
  <!-- $attrs.onClick will be typed -->
  <div v-bind="$attrs"></div>
</template>

inferTemplateDollarEl v2.2.4

  • Type: boolean
  • Default: false

Infers the type of $el in the template.

Example:

When true, $el inside the template will be correctly typed.

<template>
  <!-- $el is typed as the root element -->
  <div @click="$el.focus()">...</div>
</template>

inferTemplateDollarRefs v2.2.4

  • Type: boolean
  • Default: false

Infers the types of template refs for $refs in the template.

Example:

When true, $refs.myInput will be typed as HTMLInputElement | undefined in the template.

<template>
  <input ref="myInput" @input="$refs.myInput.value" />
</template>

inferTemplateDollarSlots v2.2.4

  • Type: boolean
  • Default: false

Infers the type of $slots in the template and for useSlots().

Example:

When true, $slots.default will have proper types, allowing for autocompletion of slot props.

<template>
  <slot name="default" :item="'hello'"></slot>
  <!-- $slots.default will be typed -->
  <div v-if="$slots.default">...</div>
</template>

Template Codegen

skipTemplateCodegen

  • Type: boolean
  • Default: false

If true, skips generating code for the template. This disables all template-related type checking and language features, which can be useful for performance in very large projects.

Example:

{
  "vueCompilerOptions": {
    "skipTemplateCodegen": true
  }
}

fallthroughAttributes v2.1.0

  • Type: boolean
  • Default: false

Enables type support for fallthrough attributes. This allows attributes passed to a component to be type-checked against the root element of that component's template.

Example:

<!-- Child.vue -->
<template>
  <a>...</a>
</template>

<!-- App.vue -->
<script setup>
import Child from './Child.vue';
</script>
<template>
  <!-- With fallthroughAttributes: true, 'href' is a valid prop -->
  <Child href="/" />
</template>

Warning: Since this option analyzes a large amount of types, it may significantly reduce the performance of VLS. Use with caution.

dataAttributes

  • Type: string[]
  • Default: []

Specifies a list of attribute patterns to be treated as data-* attributes, skipping type-checking for them.

Example:

To treat data-test-* attributes as valid on any component.

{
  "vueCompilerOptions": {
    "dataAttributes": ["data-test-*"]
  }
}

htmlAttributes

  • Type: string[]
  • Default: ["aria-*"]

Specifies a list of attribute patterns to be treated as plain HTML attributes, preventing them from being camelCased during compilation.

Example:

To treat my-custom-attr as a valid HTML attribute.

{
  "vueCompilerOptions": {
    "htmlAttributes": ["aria-*", "my-custom-attr"]
  }
}

optionsWrapper

  • Type: [string, string] | []
  • Default: ["(await import('${lib}')).defineComponent(", ")"]

Specifies a wrapper to be used around the exported object in a script block when using export default.

Example:

To use a custom wrapper.

{
  "vueCompilerOptions": {
    "optionsWrapper": ["myWrapper(", ")"]
  }
}

fallthroughComponentNames v2.2.4

  • Type: string[]
  • Default: ["Transition", "KeepAlive", "Teleport", "Suspense"]

A list of component names that are considered "transparent" when collecting fallthrough attributes. These components pass their attributes through to their children.

Example:

To add a custom wrapper component to the list.

{
  "vueCompilerOptions": {
    "fallthroughComponentNames": ["Transition", "KeepAlive", "Teleport", "Suspense", "MyWrapper"]
  }
}

Style

resolveStyleImports v3.0.0

  • Type: boolean
  • Default: false

When true, generates type imports for CSS files imported via <style src="..."> or @import "...".

Example:

{
  "vueCompilerOptions": {
    "resolveStyleImports": true
  }
}
<!-- With resolveStyleImports: true, types will be generated for external CSS -->
<style src="./styles.css"></style>

resolveStyleClassNames v3.0.0

  • Type: boolean | "scoped"
  • Default: "scoped"

Controls how CSS class names are resolved for autocompletion and go-to-definition in the template. By default, it only resolves class names from <style scoped> blocks.

Example:

To resolve class names from all style blocks, not just scoped ones.

{
  "vueCompilerOptions": {
    "resolveStyleClassNames": true
  }
}

Language Features

jsxSlots

  • Type: boolean
  • Default: false

Enables experimental support for JSX slot syntax.

Example:

{
  "vueCompilerOptions": {
    "jsxSlots": true
  }
}

macros

  • Type: Record<string, string[]>
  • Default: { defineProps: ['defineProps'], defineSlots: ['defineSlots'], defineEmits: ['defineEmits'], defineExpose: ['defineExpose'], defineModel: ['defineModel'], defineOptions: ['defineOptions'], withDefaults: ['withDefaults'] }

Allows you to configure custom identifiers for Vue's script setup macros.

Example:

To use myProps as an alias for defineProps.

{
  "vueCompilerOptions": {
    "macros": {
      "defineProps": ["defineProps", "myProps"]
    }
  }
}

composables v2.2.0

  • Type: Record<string, string[]>
  • Default: { useAttrs: ['useAttrs'], useCssModule: ['useCssModule'], useSlots: ['useSlots'], useTemplateRef: ['useTemplateRef', 'templateRef'] }

Allows you to configure custom identifiers for built-in composables that have special type support.

Example:

To use myAttrs as an alias for useAttrs.

{
  "vueCompilerOptions": {
    "composables": {
      "useAttrs": ["useAttrs", "myAttrs"]
    }
  }
}
useAttrs v2.2.2

Provides type support for useAttrs() and $attrs.

useCssModule v2.1.0

Provides type support with <style module="...">.

useSlots v2.2.0

Provides type support for useSlots() and $slots.

useTemplateRef v2.1.0

Provides type support with <Comp ref="...">.

By default, templateRef can also trigger this composable, making it easier to provide a consistent development experience equivalent to useTemplateRef for users of lower versions using VueUse.

Plugins

plugins

  • Type: string[]
  • Default: []

An array of paths to Vue language plugins. Plugins can extend the functionality of the language server.

Example:

To use the Pug plugin.

{
  "vueCompilerOptions": {
    "plugins": ["@vue/language-plugin-pug"]
  }
}

Experimental

experimentalModelPropName

  • Type: Record<string, Record<string, boolean | Record<string, string> | Record<string, string>[]>>
  • Default: { '': { input: true }, value: { input: { type: 'text' }, textarea: true, select: true } }

Configures the prop and event names for v-model on different elements. This is an advanced option for customizing v-model behavior.

Example:

To make v-model on a custom element bind to the content prop.

{
  "vueCompilerOptions": {
    "experimentalModelPropName": {
      "my-editor": {
        "content": true
      }
    }
  }
}

Clone this wiki locally