Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 38 ยท Project Structure and Config

TypeScript in Vite

Learn how Vite handles TypeScript by stripping types with esbuild, what isolatedModules and verbatimModuleSyntax mean, how to set up tsconfig, and how to type check with tsc.

TypeScript works in Vite with no setup: rename a file to .ts and import it. But "works" has a specific meaning that surprises people. Vite removes the types and runs the JavaScript that is left; it does not check the types. Understanding this one design choice explains the right tsconfig.json, why some TypeScript features are discouraged, and how to get type errors in CI.

Vite is not installed on this site, so config files are read-only. The runnable examples use TypeScript on Piston with type stripping, which is the same idea Vite applies with esbuild.

Transpile only

During development Vite hands each .ts and .tsx file to esbuild, which deletes type annotations, interfaces and generics and writes plain JavaScript. It does this for one file at a time, with no knowledge of other files. That is why it is extremely fast, and why it cannot find a type error such as passing a string where a number is expected.

Node.js Types disappear; code runs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The wrong value runs happily. A real type check with tsc --noEmit would fail on a version without the cast. So the work is split:

Job Who does it
Remove types, produce JS Vite (esbuild)
Find type errors tsc, your editor, or a checker plugin

Type checking: three practical options

  1. Your editor shows errors as you type. No setup.
  2. tsc --noEmit in a script, run in CI and before builds:
    JSON
    {
      "scripts": {
        "build": "tsc --noEmit && vite build",
        "typecheck": "tsc --noEmit"
      }
    }
    
  3. vite-plugin-checker, which runs tsc (and ESLint or vue-tsc) in a worker and shows errors in the browser overlay during development.

For Vue use vue-tsc --noEmit, because plain tsc does not understand .vue files.

Settings for a Vite project

The template generates a tsconfig.json like this (details vary by version):

JSON
{
  "compilerOptions": {
    "target": "ES2022",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noEmit": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "skipLibCheck": true,
    "types": ["vite/client"]
  },
  "include": ["src"]
}

What the important lines mean:

  • moduleResolution: "bundler" matches how Vite resolves imports (extensionless, package exports).
  • noEmit: true: TypeScript only checks; it never writes JavaScript. Vite produces the output.
  • isolatedModules: true: every file must be understandable alone, because esbuild transpiles one file at a time. TypeScript reports code that would need cross-file knowledge.
  • verbatimModuleSyntax: true: imports and exports are kept exactly as written unless marked type. This makes the output predictable.
  • types: ["vite/client"]: type definitions for import.meta.env, import.meta.hot, asset imports (import url from './a.png') and CSS modules.
  • target: for checking only. The real browser target is set in Vite's build.target.

Features that do not fit one-file transpiling

Because esbuild works per file, a few TypeScript features break or are unsafe:

  • Re-exporting a type without type: export { User } from './types' cannot be erased, because esbuild cannot tell whether User is a type. Write export type { User } from './types'.
  • const enum: usage across files needs the declaration. With isolatedModules TypeScript flags it. Use a regular enum, a union of strings, or an object with as const.
  • Implicit type imports: import { User } from './types' where User is only a type is erased by TypeScript but kept by verbatimModuleSyntax. Use import type { User }.
  • Legacy decorators need compiler flags (experimentalDecorators); standard decorators are supported by newer esbuild versions.

This stand-in shows why a one-file tool needs the type keyword. It "erases" imports the way a naive per-file tool would.

Node.js Stand-in: why import type matters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

vite-env.d.ts

The template includes src/vite-env.d.ts with one line:

TypeScript
/// <reference types="vite/client" />

It brings in Vite's client types: without it, import.meta.env and asset imports show errors in the editor. Extend it with your own variables (see Modes and Environment Variables).

Config file typing: tsconfig.node.json

Your vite.config.ts runs in Node, not the browser, so it is usually checked with a different config:

JSON
{
  "compilerOptions": {
    "target": "ES2023",
    "lib": ["ES2023"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "noEmit": true,
    "strict": true,
    "types": ["node"]
  },
  "include": ["vite.config.ts"]
}

The main tsconfig.json then uses project references ("references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]) in newer templates. The split keeps DOM types out of Node code and Node types out of browser code.

Paths and aliases

Remember to mirror any resolve.alias in compilerOptions.paths (Aliases and Path Resolution).

A second look at erasable syntax

TypeScript constructs split into two groups: erasable (types, interfaces, generics, as, !, annotations) and runtime (enums, namespaces, parameter properties). Per-file tools handle both, but modern setups (and Node's own type stripping) prefer erasable-only TypeScript. This option enforces it:

JSON
{ "compilerOptions": { "erasableSyntaxOnly": true } }
Node.js Erasable and non-erasable syntax

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Does Vite report TypeScript type errors?

    esbuild removes types for speed and does not check them. Run tsc, vue-tsc or vite-plugin-checker.
  2. 2. Why is isolatedModules recommended in a Vite project?

    esbuild looks at one file at a time. isolatedModules makes TypeScript warn about patterns that cannot be compiled that way.
  3. 3. What is the correct way to re-export only a type?

    The type keyword tells a per-file transpiler the export can be erased.
  4. 4. What does the line /// <reference types="vite/client" /> provide?

    It loads Vite's client type definitions so the editor understands Vite-specific features.

Summary

  • Vite strips TypeScript types with esbuild and does not type check.
  • Check types with your editor, tsc --noEmit (or vue-tsc), or vite-plugin-checker.
  • Use moduleResolution: "bundler", noEmit, isolatedModules and verbatimModuleSyntax.
  • Mark type-only imports and exports with type; avoid const enum.
  • Add vite/client types, and mirror aliases in paths.

Next: Dev Server Options