{"id":15044,"library":"vue-tsc","title":"Vue Type Checker","description":"vue-tsc is a command-line tool designed to integrate TypeScript's `tsc` compiler with Vue's Single File Components (SFCs). It functions as a wrapper around `tsc`, enabling full TypeScript type-checking and declaration file generation for `.vue` files by transforming them into virtual TypeScript code. The current stable version is 3.2.7, part of the actively developed `vuejs/language-tools` monorepo, receiving frequent updates with several patch releases per month. Its key differentiator is providing robust, performant type-checking for Vue applications within existing TypeScript ecosystems, leveraging `tsconfig.json` for configuration. It requires TypeScript 5.0.0 or higher as a peer dependency.","status":"active","version":"3.2.7","language":"javascript","source_language":"en","source_url":"https://github.com/vuejs/language-tools","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-tsc","lang":"bash","label":"npm"},{"cmd":"yarn add vue-tsc","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-tsc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for core type checking functionality. Specifies TypeScript >=5.0.0.","package":"typescript","optional":false}],"imports":[{"note":"The primary programmatic entry point for executing vue-tsc's CLI logic. Primarily an ESM package; CommonJS require() may lead to import errors. Accepts an options object to pass CLI arguments and tsc path.","wrong":"const { run } = require('vue-tsc')","symbol":"run","correct":"import { run } from 'vue-tsc'"},{"note":"Inferred type for configuration options found in `tsconfig.json` under `vueCompilerOptions`. Useful for programmatic configuration or extending Vue language tools.","symbol":"VueCompilerOptions","correct":"import type { VueCompilerOptions } from 'vue-tsc'"},{"note":"Inferred type for diagnostic messages produced by the type checker, often for custom error handling or reporting. This type is likely a re-export from TypeScript's own Diagnostic type, potentially augmented for Vue-specific contexts.","symbol":"Diagnostic","correct":"import type { Diagnostic } from 'vue-tsc'"}],"quickstart":{"code":"import { run } from 'vue-tsc';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\n// Create a dummy tsconfig.json for demonstration if not present\nconst tsconfigPath = path.resolve('./tsconfig.json');\nif (!fs.existsSync(tsconfigPath)) {\n  fs.writeFileSync(tsconfigPath, JSON.stringify({\n    \"compilerOptions\": {\n      \"target\": \"esnext\",\n      \"module\": \"esnext\",\n      \"moduleResolution\": \"bundler\",\n      \"strict\": true,\n      \"jsx\": \"preserve\",\n      \"lib\": [\"esnext\", \"dom\"],\n      \"types\": [\"node\", \"vue\"]\n    },\n    \"vueCompilerOptions\": {\n      \"extensions\": [\".vue\"]\n    },\n    \"include\": [\"./**/*.ts\", \"./**/*.d.ts\", \"./**/*.vue\"]\n  }, null, 2));\n}\n\n// Create a dummy Vue SFC for type checking\nconst vueFilePath = path.resolve('./MyComponent.vue');\nif (!fs.existsSync(vueFilePath)) {\n  fs.writeFileSync(vueFilePath, `\n<script setup lang=\"ts\">\nimport { ref } from 'vue';\nconst message: string = ref('Hello Vue 3 and TypeScript').value;\n// Intentional error for demonstration: assign number to string\n// const errorVal: string = 123; \n</script>\n\n<template>\n  <div>{{ message }}</div>\n</template>\n`);\n}\n\nconsole.log('Running vue-tsc programmatically with --noEmit...');\n\n// Execute vue-tsc with command-line arguments\ntry {\n  run({\n    args: ['--noEmit', '--project', tsconfigPath] // Equivalent to 'vue-tsc --noEmit --project ./tsconfig.json'\n  });\n  console.log('vue-tsc completed successfully (noEmit). No type errors found.');\n} catch (e) {\n  console.error('vue-tsc encountered an error:', e.message);\n  console.error('Check MyComponent.vue for type errors or tsconfig.json configuration.');\n  process.exit(1);\n}\n","lang":"typescript","description":"Demonstrates programmatic execution of `vue-tsc --noEmit` to type-check Vue SFCs in a project. It sets up a minimal `tsconfig.json` and a `.vue` file for context."},"warnings":[{"fix":"Upgrade your project's TypeScript dependency: `npm install typescript@^5.0.0 --save-dev` or `yarn add typescript@^5.0.0 --dev`.","message":"vue-tsc requires TypeScript version 5.0.0 or higher. Projects using older TypeScript versions will fail during installation or execution.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"If you need detailed programmatic interaction with Vue language services or diagnostics, explore the `@vue/language-tools` monorepo for more granular packages like `@vue/language-core`.","message":"vue-tsc is primarily a CLI tool. While it offers a programmatic `run` function, its API is minimal and designed for integrating the CLI, not for fine-grained language service control. For advanced programmatic usage, consider `@vue/language-core` or `@vue/language-service` packages.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Add `\"vueCompilerOptions\": { \"extensions\": [\".vue\", \".my-custom-ext\"] }` to your `tsconfig.json`.","message":"By default, `vue-tsc` only processes `.vue` files. If you use custom extensions (e.g., `.md`, `.vitepress`) for Vue components, you must explicitly list them in `vueCompilerOptions.extensions` in your `tsconfig.json`.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Understand that `vue-tsc` operates on an in-memory representation. For debugging type issues, rely on the error messages and the IDE's Vue language features (if using VSCode with Volar/Vue Language Features).","message":"vue-tsc internally transforms `.vue` files into virtual TypeScript code. This means you won't find corresponding `.ts` files on disk for your Vue SFCs during compilation, which can be confusing if you expect traditional compiler output.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `vue-tsc` is installed and configured in your `package.json` scripts (e.g., `\"type-check\": \"vue-tsc --noEmit\"`) and that your `tsconfig.json` includes `\"*.vue\"` in its `include` array, along with appropriate `vueCompilerOptions`.","cause":"TypeScript (tsc) does not natively understand `.vue` file imports. This typically indicates `vue-tsc` is not correctly integrated or the project's `tsconfig.json` is misconfigured.","error":"Module not found: Error: Can't resolve './MyComponent.vue' in '...' OR Cannot find module './MyComponent.vue' or its corresponding type declarations."},{"fix":"Install or upgrade TypeScript to version 5.0.0 or newer: `npm install typescript@^5.0.0 --save-dev` (or `yarn add typescript@^5.0.0 --dev`).","cause":"`vue-tsc` has a strict peer dependency on TypeScript version 5.0.0 or higher.","error":"The 'typescript' package is not installed or its version is less than 5.0.0."},{"fix":"Verify that your Vue component's props and emits are correctly defined using `defineProps` and `defineEmits` with explicit generic type arguments in `<script setup>`, and ensure any custom types are properly imported and available.","cause":"Incorrect type inference for props, data, or methods within a Vue component, often due to missing `defineProps` or `defineEmits`, or incorrect type definitions.","error":"Property 'someProp' does not exist on type 'VueComponentInstance' (or similar type error within a Vue template or script)."}],"ecosystem":"npm"}