Usando Vue con TypeScript ​

Un sistema de tipos como TypeScript puede detectar muchos errores comunes mediante análisis estático en tiempo de construcción. Esto reduce la probabilidad de errores en tiempo de ejecución en producción, y también nos permite refactorizar código con mayor confianza en aplicaciones de gran escala. TypeScript también mejora la ergonomía del desarrollador mediante la auto-completación basada en tipos en los IDEs.

Vue está escrito en TypeScript y proporciona soporte de primera clase para TypeScript. Todos los paquetes oficiales de Vue vienen con declaraciones de tipo incluidas que deberían funcionar de inmediato.

Configuración del Proyecto ​

create-vue, la herramienta oficial de scaffolding de proyectos, ofrece las opciones para configurar un proyecto Vue impulsado por Vite y listo para TypeScript.

Resumen ​

Con una configuración basada en Vite, el servidor de desarrollo y el empaquetador son solo de transpilación y no realizan ninguna verificación de tipos. Esto asegura que el servidor de desarrollo de Vite se mantenga increíblemente rápido incluso cuando se usa TypeScript.

• Durante el desarrollo, recomendamos depender de una buena configuración de IDE para obtener retroalimentación instantánea sobre errores de tipo.

• Si usas SFCs, utiliza la utilidad vue-tsc para la verificación de tipos en línea de comandos y la generación de declaraciones de tipo. vue-tsc es un wrapper para tsc, la interfaz de línea de comandos propia de TypeScript. Funciona en gran medida igual que tsc excepto que soporta SFCs de Vue además de archivos TypeScript. Puedes ejecutar vue-tsc en modo de observación (watch mode) en paralelo con el servidor de desarrollo de Vite, o usar un plugin de Vite como vite-plugin-checker que ejecuta las verificaciones en un hilo de trabajo (worker thread) separado.

• Vue CLI también proporciona soporte para TypeScript, pero ya no se recomienda. Consulta las notas a continuación.

Soporte para IDE ​

• Visual Studio Code (VS Code) es fuertemente recomendado por su excelente soporte inmediato para TypeScript.

  • Vue - Oficial (anteriormente Volar) es la extensión oficial de VS Code que proporciona soporte para TypeScript dentro de los SFCs de Vue, junto con muchas otras excelentes características.

  TIP

  La extensión Vue - Oficial reemplaza a Vetur, nuestra extensión oficial anterior de VS Code para Vue 2. Si tienes Vetur instalado actualmente, asegúrate de deshabilitarlo en proyectos de Vue 3.

• WebStorm también proporciona soporte inmediato para TypeScript y Vue. Otros IDEs de JetBrains también los soportan, ya sea de inmediato o mediante un plugin gratuito. A partir de la versión 2023.2, WebStorm y el plugin de Vue vienen con soporte integrado para el Vue Language Server. Puedes configurar el servicio de Vue para usar la integración de Volar en todas las versiones de TypeScript, en Ajustes > Lenguajes y Frameworks > TypeScript > Vue. Por defecto, Volar se utilizará para las versiones de TypeScript 5.0 y superiores.

Configuración de tsconfig.json ​

Los proyectos configurados mediante create-vue incluyen un tsconfig.json preconfigurado. La configuración base se abstrae en el paquete @vue/tsconfig. Dentro del proyecto, usamos Project References para asegurar tipos correctos para el código que se ejecuta en diferentes entornos (por ejemplo, el código de la aplicación y el código de prueba deberían tener diferentes variables globales).

Al configurar tsconfig.json manualmente, algunas opciones notables incluyen:

• compilerOptions.isolatedModules se establece en true porque Vite usa esbuild para transpilación de TypeScript y está sujeto a limitaciones de transpilación de archivo único. compilerOptions.verbatimModuleSyntax es un superconjunto de isolatedModules y también es una buena opción, es lo que usa @vue/tsconfig.

• Si estás usando la Options API, necesitas establecer compilerOptions.strict en true (o al menos habilitar compilerOptions.noImplicitThis, que es parte del flag strict) para aprovechar la verificación de tipos de this en las opciones del componente. De lo contrario, this será tratado como any.

• Si has configurado alias de resolutor en tu herramienta de construcción, por ejemplo, el alias @/* configurado por defecto en un proyecto create-vue, también necesitas configurarlo para TypeScript a través de compilerOptions.paths.

• Si tienes la intención de usar TSX con Vue, establece compilerOptions.jsx en "preserve", y establece compilerOptions.jsxImportSource en "vue".

Ver también:

• Documentación oficial de opciones del compilador de TypeScript
• Advertencias de compilación de TypeScript de esbuild

Nota sobre Vue CLI y ts-loader ​

En configuraciones basadas en webpack, como Vue CLI, es común realizar la verificación de tipos como parte de la pipeline de transformación de módulos, por ejemplo con ts-loader. Sin embargo, esta no es una solución limpia porque el sistema de tipos necesita conocimiento de todo el grafo de módulos para realizar las verificaciones de tipos. El paso de transformación de un módulo individual simplemente no es el lugar adecuado para esta tarea. Esto lleva a los siguientes problemas:

• ts-loader solo puede verificar tipos en el código post-transformación. Esto no se alinea con los errores que vemos en los IDEs o de vue-tsc, los cuales se mapean directamente al código fuente.

• La verificación de tipos puede ser lenta. Cuando se realiza en el mismo hilo / proceso con transformaciones de código, afecta significativamente la velocidad de construcción de toda la aplicación.

• Ya tenemos la verificación de tipos ejecutándose directamente en nuestro IDE en un proceso separado, por lo que el costo de ralentizar la experiencia de desarrollo simplemente no es un buen intercambio.

Si actualmente estás usando Vue 3 + TypeScript a través de Vue CLI, recomendamos encarecidamente migrar a Vite. También estamos trabajando en opciones de CLI para habilitar el soporte de TS solo para transpilación, de modo que puedas cambiar a vue-tsc para la verificación de tipos.

Notas de Uso General ​

defineComponent() ​

Para que TypeScript infiera correctamente los tipos dentro de las opciones del componente, necesitamos definir componentes con defineComponent():

import { defineComponent } from 'vue'

export default defineComponent({
  // type inference enabled
  props: {
    name: String,
    msg: { type: String, required: true }
  },
  data() {
    return {
      count: 1
    }
  },
  mounted() {
    this.name // type: string | undefined
    this.msg // type: string
    this.count // type: number
  }
})

defineComponent() también soporta la inferencia de las props pasadas a setup() cuando se usa la Composition API sin <script setup>:

import { defineComponent } from 'vue'

export default defineComponent({
  // type inference enabled
  props: {
    message: String
  },
  setup(props) {
    props.message // type: string | undefined
  }
})

Ver también:

• Nota sobre el Tree-shaking de webpack
• pruebas de tipo para defineComponent

Uso en Componentes de Archivo Único ​

Para usar TypeScript en SFCs, añade el atributo lang="ts" a las etiquetas <script>. Cuando lang="ts" está presente, todas las expresiones de el template también disfrutan de una verificación de tipos más estricta.

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  data() {
    return {
      count: 1
    }
  }
})
</script>

<template>
  <!-- type checking and auto-completion enabled -->
  {{ count.toFixed(2) }}
</template>

lang="ts" también se puede usar con <script setup>:

<script setup lang="ts">
// TypeScript enabled
import { ref } from 'vue'

const count = ref(1)
</script>

<template>
  <!-- type checking and auto-completion enabled -->
  {{ count.toFixed(2) }}
</template>

TypeScript en Templates ​

La etiqueta <template> también soporta TypeScript en expresiones de enlace (binding expressions) cuando se usa <script lang="ts"> o <script setup lang="ts">. Esto es útil en casos donde necesitas realizar una conversión de tipos (type casting) en expresiones de el template.

Aquí tienes un ejemplo forzado:

<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  <!-- error because x could be a string -->
  {{ x.toFixed(2) }}
</template>

Esto se puede solucionar con una conversión de tipos (type cast) en línea:

<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  {{ (x as number).toFixed(2) }}
</template>

Uso con TSX ​

Vue también soporta la creación de componentes con JSX / TSX. Los detalles se cubren en la guía Función de Renderizado y JSX.

Componentes Genéricos ​

Los componentes genéricos se soportan en dos casos:

• En SFCs: <script setup> con el atributo generic
• Componentes de función de renderizado / JSX: la firma de función de defineComponent()

Recetas Específicas de la API ​

• TS con Composition API
• TS con Options API