2.5: typescript

Author: yyx990803

src/v2/guide/typescript.md

@@ -4,117 +4,75 @@ type: guide
 order: 404
 ---
 
-## Important 2.2.0+ Change Notice for TS + webpack 2 users
-
-In Vue 2.2.0+ we introduced dist files exposed as ES modules, which will be used by default by webpack 2. Unfortunately, this introduced an unintentional breaking change because with TypeScript + webpack 2, `import Vue = require('vue')` will now return a synthetic ES module object instead of Vue itself.
-
-We plan to move all official declarations to use ES-style exports in the future. Please see [Recommended Configuration](#Recommended-Configuration) below on a future-proof setup.
+> 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](https://medium.com/the-vue-point/upcoming-typescript-changes-in-vue-2-5-e9bd7e2ecf08) 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](https://github.com/vuejs/vue/tree/dev/types) for [TypeScript](https://www.typescriptlang.org/) - not only in Vue core, but also for [vue-router](https://github.com/vuejs/vue-router/tree/dev/types) and [vuex](https://github.com/vuejs/vuex/tree/dev/types) as well.
 
 Since these are [published on NPM](https://cdn.jsdelivr.net/npm/vue/types/), 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.
 
+We also plan to provide an option to scaffold a ready-to-go Vue + TypeScript project in `vue-cli` in the near future.
+
 ## Recommended Configuration
 
 ``` js
 // tsconfig.json
 {
   "compilerOptions": {
-    // ... other options omitted
-    "allowSyntheticDefaultImports": true,
-    "lib": [
-      "dom",
-      "es5",
-      "es2015.promise"
-    ]
-  }
-}
-```
-
-Note the `allowSyntheticDefaultImports` option allows us to use the following:
-
-``` js
-import Vue from 'vue'
-```
-
-instead of:
-
-``` js
-import Vue = require('vue')
-```
-
-The former (ES module syntax) is recommended because it is consistent with recommended plain ES usage, and in the future we are planning to move all official declarations to use ES-style exports.
-
-In addition, if you are using TypeScript with webpack 2, the following is also recommended:
-
-``` js
-{
-  "compilerOptions": {
-    // ... other options omitted
+    // 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"
   }
 }
 ```
 
-This tells TypeScript to leave the ES module import statements intact, which in turn allows webpack 2 to take advantage of ES-module-based tree-shaking.
-
 See [TypeScript compiler options docs](https://www.typescriptlang.org/docs/handbook/compiler-options.html) for more details.
 
-## Using Vue's Type Declarations
+## Development Tooling
 
-Vue's type definition exports many useful [type declarations](https://github.com/vuejs/vue/blob/dev/types/index.d.ts). For example, to annotate an exported component options object (e.g. in a `.vue` file):
+For developing Vue applications with TypeScript, we strongly recommend using [Visual Studio Code](https://code.visualstudio.com/), which provides great out-of-the-box support for TypeScript.
 
-``` ts
-import Vue, { ComponentOptions } from 'vue'
-
-export default {
-  props: ['message'],
-  template: '<span>{{ message }}</span>'
-} as ComponentOptions<Vue>
-```
+If you are using [single-file components](./single-file-components.html) (SFCs), get the awesome [Vetur extension](https://github.com/vuejs/vetur), which provides TypeScript inference inside SFCs and many other great features.
 
-## Class-Style Vue Components
+## Basic Usage
 
-Vue component options can easily be annotated with types:
+To let TypeScript properly infer types inside Vue component options, you need to define components with `Vue.component` or `Vue.extend`:
 
 ``` ts
-import Vue, { ComponentOptions }  from 'vue'
+import Vue from 'vue'
 
-// Declare the component's type
-interface MyComponent extends Vue {
-  message: string
-  onClick (): void
-}
+const Component = Vue.extend({
+  // type inference enabled
+})
 
-export default {
-  template: '<button @click="onClick">Click!</button>',
-  data: function () {
-    return {
-      message: 'Hello!'
-    }
-  },
-  methods: {
-    onClick: function () {
-      // TypeScript knows that `this` is of type MyComponent
-      // and that `this.message` will be a string
-      window.alert(this.message)
-    }
-  }
-// We need to explicitly annotate the exported options object
-// with the MyComponent type
-} as ComponentOptions<MyComponent>
+const Component = {
+  // this will NOT have type inference,
+  // because TypeScript can't tell this is options for a Vue component.
+}
 ```
 
-Unfortunately, there are a few limitations here:
+Note that when using Vetur with SFCs, type inference will be automatically applied to the default export, so there's no need to wrap it in `Vue.extend`:
 
-- __TypeScript can't infer all types from Vue's API.__ For example, it doesn't know that the `message` property returned in our `data` function will be added to the `MyComponent` instance. That means if we assigned a number or boolean value to `message`, linters and compilers wouldn't be able to raise an error, complaining that it should be a string.
+``` html
+<template>
+  ...
+</template>
 
-- Because of the previous limitation, __annotating types like this can be verbose__. The only reason we have to manually declare `message` as a string is because TypeScript can't infer the type in this case.
+<script lang="ts">
+export default {
+  // type inference enabled
+}
+</script>
+```
+
+## Class-Style Vue Components
 
-Fortunately, [vue-class-component](https://github.com/vuejs/vue-class-component) can solve both of these problems. It's an official companion library that allows you to declare components as native JavaScript classes, with a `@Component` decorator. As an example, let's rewrite the above component:
+If you prefer a class-based API when declaring components, you can use the officially maintained [vue-class-component](https://github.com/vuejs/vue-class-componen) decorator:
 
 ``` ts
 import Vue from 'vue'
@@ -136,9 +94,7 @@ export default class MyComponent extends Vue {
 }
 ```
 
-With this syntax alternative, our component definition is not only shorter, but TypeScript can also infer the types of `message` and `onClick` without explicit interface declarations. This strategy even allows you to handle types for computed properties, lifecycle hooks, and render functions. For full usage details, see [the vue-class-component docs](https://github.com/vuejs/vue-class-component#vue-class-component).
-
-## Declaring Types of Vue Plugins
+## 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](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation).
 
@@ -162,7 +118,7 @@ After including the above code as a declaration file (like `my-property.d.ts`) i
 
 ```ts
 var vm = new Vue()
-console.log(vm.$myProperty) // This will be successfully compiled
+console.log(vm.$myProperty) // This should compile successfully
 ```
 
 You can also declare additional global properties and component options:
@@ -172,9 +128,9 @@ import Vue from 'vue'
 
 declare module 'vue/types/vue' {
   // Global properties can be declared
-  // by using `namespace` instead of `interface`
-  namespace Vue {
-    const $myGlobal: string
+  // on the VueConstructor interface
+  interface VueConstructor {
+    $myGlobal: string
   }
 }