Migrate Vue 2 to TypeScript

Install TypeScript

This guide assumes Vue 2.7.16, which includes <script setup> and Composition Api support. Earlier Vue 2 releases need a different setup and should be upgraded first. Vue 2 itself is end of life, so treat TypeScript adoption as one step toward Vue 3 rather than a replacement for the framework migration.

npm install -D typescript@^6.0.0 vue-tsc@^3.3.8

Vite transpiles TypeScript but does not type-check it. Add a script such as "type-check": "vue-tsc --noEmit" and run it in CI. The version pin above avoids TypeScript 7 until vue-tsc supports its package exports.

Create a `tsconfig.json`

Create tsconfig.json in the root of your project folder and add the following content:

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "allowJs": true,
    "types": ["vite/client"],

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "preserve",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    /* Path aliases in case you use them */
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "vueCompilerOptions": {
    "target": 2.7
  }
}

Ensure your aliases are set up correctly according to your Vite configuration.

Migrate Components

When using TypeScript with the Options Api, it doesn’t feel as natural as using it with the Composition Api. To type your data appropriately, you have to use return signatures or cast it to the correct type.

<template>
  <div>
    <h1>Options Api</h1>
    <p>{{ msg }}</p>
    <button @click="hello">Log values</button>
  </div>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import type { PropType } from "vue";

type SomeType = {
  foo: string;
};

type MyData = {
  msg: string;
  items: string[];
};

export default defineComponent({
  name: "OptionsApi",
  props: {
    prop1: {
      type: Object as PropType<SomeType>,
    },
  },
  data(): MyData {
    return {
      msg: "Hello World",
      items: [],
    };
  },
  methods: {
    hello() {
      console.log(this.msg, this.items, this.prop1);
    },
  },
});
</script>

<template>
  <div>
    <h1>Script Setup</h1>
    <p>{{ msg }}</p>
    <button @click="hello">Log values</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";

type SomeType = {
  foo: string;
};

const props = defineProps<{ prop1?: SomeType }>();

const msg = ref("Hello World");
const items = ref<string[]>([]);

const hello = () => {
  console.log(msg.value, items.value, props.prop1);
};
</script>

Strategy

Migrating to TypeScript can become overwhelming quickly. You can ease the process by migrating your components one by one. Focus on components that utilize external component libraries. This will help you later when migrating those libraries to Vue 3 since errors will become evident.

Need Assistance?

If you need help with your migration, feel free to contact me via email or visit the contact page. I offer professional assistance and guidance for migrations at fair rates.