Vite Impl Project Setup

vite-impl-project-setup

Quick Reference

Project Creation (create-vite)

Omit --template for interactive template selection.

Available Templates

CLI Commands

Common CLI Flags

Critical Warnings

ALWAYS set isolatedModules: true in tsconfig.json — Vite transpiles TypeScript without type information. Without this flag, code that relies on cross-file type analysis (like const enum re-exports) will silently produce incorrect output.

NEVER rely on Vite for type checking — Vite performs transpile-only. ALWAYS run tsc --noEmit separately for type safety, either in CI or as a parallel dev process.

NEVER set envPrefix to '' in vite.config.ts — this exposes ALL environment variables (including secrets like DB_PASSWORD) to client-side code.

NEVER omit /// <reference types="vite/client" /> from vite-env.d.ts — without it, TypeScript cannot resolve import.meta.env, asset imports (.svg, .png), or HMR types.

Decision Tree: New Project Setup

Need a new Vite project?
├── Greenfield project → Use create-vite with --template
│   ├── React project?
│   │   ├── Need fastest dev builds → react-swc-ts (SWC compiler)
│   │   └── Need Babel plugins → react-ts (Babel compiler)
│   ├── Vue project? → vue-ts
│   ├── Svelte project? → svelte-ts
│   ├── No framework? → vanilla-ts
│   └── Other framework? → Check create-vite templates list
│
├── Adding Vite to existing project → Manual setup
│   ├── Install vite as devDependency
│   ├── Create vite.config.ts with framework plugin
│   ├── Move/create index.html at project root
│   ├── Add <script type="module" src="/src/main.ts"> to index.html
│   └── Add dev/build/preview scripts to package.json
│
└── TypeScript project?
    ├── ALWAYS set isolatedModules: true in tsconfig.json
    ├── ALWAYS create src/vite-env.d.ts with /// reference types
    ├── ALWAYS run tsc --noEmit separately for type checking
    └── ALWAYS use type-only imports: import type { T } from '...'

Project Structure

my-app/
├── index.html                 # Entry point (MUST be at project root)
├── public/                    # Static assets (copied as-is, no processing)
│   └── favicon.ico
├── src/
│   ├── main.ts                # Application entry (referenced from index.html)
│   ├── App.tsx                # Root component (framework-dependent)
│   ├── vite-env.d.ts          # Vite client type declarations
│   └── assets/                # Processed assets (hashed in build)
│       └── logo.svg
├── vite.config.ts             # Vite configuration
├── tsconfig.json              # TypeScript configuration
├── package.json               # Dependencies and scripts
└── .gitignore                 # Source control exclusions

ALWAYS place index.html at the project root — Vite uses it as the entry point, NOT inside public/ or src/. The dev server maps <root>/index.html to http://localhost:5173/.

TypeScript Configuration

Required tsconfig.json Settings

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "isolatedModules": true,
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "types": ["vite/client"]
  },
  "include": ["src"]
}

Critical Settings Explained

vite-env.d.ts (REQUIRED)

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

This file MUST exist in src/ to provide TypeScript with Vite-specific type definitions. It enables types for:

• import.meta.env.VITE_* variables
• Asset imports (import logo from './logo.svg')
• import.meta.hot HMR API

Type Checking Workflow

Vite does NOT type-check — it only transpiles. ALWAYS run type checking separately:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "preview": "vite preview",
    "typecheck": "tsc --noEmit",
    "typecheck:watch": "tsc --noEmit --watch"
  }
}

Framework Plugin Setup

Framework Plugin Table

Minimal vite.config.ts (React + TypeScript)

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'

export default defineConfig({
  plugins: [react()],
})

JSX Configuration (Non-Framework)

For Vite 8+ (Oxc transformer):

export default defineConfig({
  oxc: {
    jsx: {
      runtime: 'classic',
      pragma: 'h',
      pragmaFrag: 'Fragment',
    },
  },
})

For Vite 6/7 (esbuild transformer):

export default defineConfig({
  esbuild: {
    jsxFactory: 'h',
    jsxFragment: 'Fragment',
    jsxInject: `import { h, Fragment } from 'preact'`,
  },
})

CSS Preprocessor Setup

Install the preprocessor package only — NO Vite plugins needed:

ALWAYS prefer sass-embedded over sass — it is significantly faster for large projects.

Source Control (.gitignore)

node_modules
dist
*.local
.env.local
.env.*.local

ALWAYS ignore node_modules and dist. ALWAYS ignore .env.local and .env.*.local — these contain environment-specific secrets. NEVER ignore vite.config.ts, tsconfig.json, or package-lock.json / pnpm-lock.yaml — these are required for reproducible builds.

Reference Links

• references/templates.md — All create-vite templates with framework plugin setup details
• references/examples.md — Step-by-step project creation workflows and configuration examples
• references/anti-patterns.md — Common project setup mistakes and how to avoid them

Official Sources

• https://vite.dev/guide/
• https://vite.dev/config/
• https://vite.dev/guide/features.html#typescript
• https://vite.dev/guide/cli.html