SFC Checking Toolchain

## What the build actually does with TypeScript In a Vue 3 project built with Vite, TypeScript in `.ts` files and in `<script lang="ts">` blocks is **transpiled**, not **type-checked**. The Vue TypeScript guide says so directly: with a Vite-based setup, the dev server and the bundler are transpilation-only and do not perform any type-checking. Transpiling means removing type annotations and turning the rest into JavaScript, **one file at a time**. A type checker instead needs the whole program: every import, every declaration, every component's props. The guide adds that the transpiler works under single-file limitations, which is why the scaffolded `tsconfig` enables `isolatedModules` (or the stricter `verbatimModuleSyntax`) so that code which a per-file transpiler cannot handle is flagged by the checker. The consequence: the following component builds and runs, and fails only at runtime or never visibly. ```vue <script setup lang="ts"> const props = defineProps<{ price: number }>() </script> <template> <span>{{ props.price.toFixd(2) }}</span> </template> ``` ## Why Vue chose this split - **Speed**: type-checking a whole project on every file change would slow the dev server down; stripping types per file is cheap. - **One source of truth**: errors should map back to the source you wrote. The guide criticises checking inside the webpack transform pipeline with `ts-loader`: it can only check post-transform code, which does not align with the errors shown by the IDE or `vue-tsc`. - **Separation**: the editor already runs a type checker in a separate process, so doing it again inside the bundler is a poor trade. ## What catches the errors | Where | Tool | When it runs | |---|---|---| | Editor | Vue - Official extension (Vue language server) | continuously while you type | | Terminal, dev time | `vue-tsc --noEmit --watch` | alongside the dev server | | Script or CI | `vue-tsc --noEmit` (or `vue-tsc --build` with project references) | before or alongside the build | `vue-tsc` is a wrapper around `tsc` that also understands `.vue` files, including the expressions in templates, so it reports errors plain `tsc` cannot see. ## Wiring it into the pipeline 1. Add a script such as `"type-check": "vue-tsc --noEmit"`. 2. Run it in CI as its own step, so a type error fails the pipeline even though `vite build` succeeds. 3. Optionally make the production build depend on it, for example by running both in the build script. 4. Keep it fast by checking the right tsconfig: with project references, point it at the app config or use `--build`. ```json { "scripts": { "type-check": "vue-tsc --noEmit", "build": "vue-tsc --noEmit && vite build" } } ``` ## What each layer can and cannot catch | Layer | Catches | Misses | |---|---|---| | Transpile step (dev server, build) | syntax errors, invalid SFC structure, template compile errors | every type error | | Editor extension | type errors in open files, including templates | files nobody opens; teammates without the extension | | `vue-tsc` in CI | type errors across every file the tsconfig includes | files outside that tsconfig's `include` | The middle row explains why the editor alone is not a gate: it reports what a developer looks at, not the whole project. The last row explains why the CI command must point at the right configuration. ## Common misconceptions - **"`lang=\"ts\"` makes the build strict."** It only tells the transpiler and the language tools that the block is TypeScript. - **"The dev server's error overlay shows type errors."** It shows syntax and compile errors from transpiling, not type errors. - **"`tsc --noEmit` is enough."** Plain `tsc` does not understand `.vue` files, so it cannot check SFCs or their templates. - **"Editor errors will stop a bad commit."** Only if something in CI or a hook runs `vue-tsc`; the editor cannot block a merge.