190 lines (144 sloc) 6.34 KB
title type order
TypeScript Support

In Vue 2.5.0+ we have greatly improved our type declarations to work with the default object-based API. At the same time it introduces a few changes that require upgrade actions. Read this blog post for more details.

Official Declaration in NPM Packages

A static type system can help prevent many potential runtime errors, especially as applications grow. That's why Vue ships with official type declarations for TypeScript - not only in Vue core, but also for vue-router and vuex as well.

Since these are published on NPM, and the latest TypeScript knows how to resolve type declarations in NPM packages, this means when installed via NPM, you don't need any additional tooling to use TypeScript with Vue.

Recommended Configuration

// tsconfig.json
  "compilerOptions": {
    // this aligns with Vue's browser support
    "target": "es5",
    // this enables stricter inference for data properties on `this`
    "strict": true,
    // if using webpack 2+ or rollup, to leverage tree shaking:
    "module": "es2015",
    "moduleResolution": "node"

Note that you have to include strict: true (or at least noImplicitThis: true which is a part of strict flag) to leverage type checking of this in component methods otherwise it is always treated as any type.

See TypeScript compiler options docs for more details.

Development Tooling

Project Creation

Vue CLI 3 can generate new projects that use TypeScript. To get started:

# 1. Install Vue CLI, if it's not already installed
npm install --global @vue/cli

# 2. Create a new project, then choose the "Manually select features" option
vue create my-project-name

Editor Support

For developing Vue applications with TypeScript, we strongly recommend using Visual Studio Code, which provides great out-of-the-box support for TypeScript. If you are using single-file components (SFCs), get the awesome Vetur extension, which provides TypeScript inference inside SFCs and many other great features.

WebStorm also provides out-of-the-box support for both TypeScript and Vue.

Basic Usage

To let TypeScript properly infer types inside Vue component options, you need to define components with Vue.component or Vue.extend:

import Vue from 'vue'

const Component = Vue.extend({
  // type inference enabled

const Component = {
  // this will NOT have type inference,
  // because TypeScript can't tell this is options for a Vue component.

Class-Style Vue Components

If you prefer a class-based API when declaring components, you can use the officially maintained vue-class-component decorator:

import Vue from 'vue'
import Component from 'vue-class-component'

// The @Component decorator indicates the class is a Vue component
  // All component options are allowed in here
  template: '<button @click="onClick">Click!</button>'
export default class MyComponent extends Vue {
  // Initial data can be declared as instance properties
  message: string = 'Hello!'

  // Component methods can be declared as instance methods
  onClick (): void {

Augmenting Types for Use with Plugins

Plugins may add to Vue's global/instance properties and component options. In these cases, type declarations are needed to make plugins compile in TypeScript. Fortunately, there's a TypeScript feature to augment existing types called module augmentation.

For example, to declare an instance property $myProperty with type string:

// 1. Make sure to import 'vue' before declaring augmented types
import Vue from 'vue'

// 2. Specify a file with the types you want to augment
//    Vue has the constructor type in types/vue.d.ts
declare module 'vue/types/vue' {
  // 3. Declare augmentation for Vue
  interface Vue {
    $myProperty: string

After including the above code as a declaration file (like my-property.d.ts) in your project, you can use $myProperty on a Vue instance.

var vm = new Vue()
console.log(vm.$myProperty) // This should compile successfully

You can also declare additional global properties and component options:

import Vue from 'vue'

declare module 'vue/types/vue' {
  // Global properties can be declared
  // on the `VueConstructor` interface
  interface VueConstructor {
    $myGlobal: string

// ComponentOptions is declared in types/options.d.ts
declare module 'vue/types/options' {
  interface ComponentOptions<V extends Vue> {
    myOption?: string

The above declarations allow the following code to be compiled:

// Global property

// Additional component option
var vm = new Vue({
  myOption: 'Hello'

Annotating Return Types

Because of the circular nature of Vue's declaration files, TypeScript may have difficulties inferring the types of certain methods. For this reason, you may need to annotate the return type on methods like render and those in computed.

import Vue, { VNode } from 'vue'

const Component = Vue.extend({
  data () {
    return {
      msg: 'Hello'
  methods: {
    // need annotation due to `this` in return type
    greet (): string {
      return this.msg + ' world'
  computed: {
    // need annotation
    greeting(): string {
      return this.greet() + '!'
  // `createElement` is inferred, but `render` needs return type
  render (createElement): VNode {
    return createElement('div', this.greeting)

If you find type inference or member completion isn't working, annotating certain methods may help address these problems. Using the --noImplicitAny option will help find many of these unannotated methods.