Vite Agents Project Scaffolder

vite-agents-project-scaffolder

Quick Reference

Scaffolding Decision Tree

What framework?
├── React
│   ├── Need Babel plugins (relay, styled-components)? → @vitejs/plugin-react
│   └── No special Babel needs? → @vitejs/plugin-react-swc (ALWAYS prefer — 20x faster)
├── Vue
│   └── ALWAYS → @vitejs/plugin-vue
├── Svelte
│   └── ALWAYS → @sveltejs/vite-plugin-svelte
└── Vanilla TypeScript
    └── No plugin needed

What Vite Version?

ALWAYS check the installed Vite version before generating config. Vite 8 uses oxc and build.rolldownOptions; Vite 6/7 uses esbuild and build.rollupOptions.

Generated File Inventory

Critical Warnings

NEVER omit isolatedModules: true from tsconfig.json -- Vite uses transpile-only transforms that require this setting. Omitting it causes silent type-system mismatches.

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

NEVER include type: "module" in package.json when using .ts config files -- Vite handles module resolution internally. Adding it causes resolution conflicts.

ALWAYS use /// <reference types="vite/client" /> in src/vite-env.d.ts -- this provides types for import.meta.env, asset imports, and CSS modules.

ALWAYS set "moduleResolution": "bundler" in tsconfig.json -- Vite resolves modules like a bundler, not like Node.js.

ALWAYS run type checking separately with tsc --noEmit -- Vite NEVER type-checks during dev or build.

Framework Plugin Selection

Plugin Comparison Table

Plugin Configuration Patterns

React (SWC -- default choice):

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

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

React (Babel -- only when Babel plugins needed):

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

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-styled-components'],
      },
    }),
  ],
})

Vue:

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

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

Svelte:

import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'

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

Scaffolding Procedure

Step 1: Determine Project Parameters

Collect these before generating any files:

1. Framework: React / Vue / Svelte / Vanilla
2. Vite version: 6, 7, or 8 (affects config keys)
3. CSS preprocessor: None / Sass / Less / Stylus
4. Path alias: @ -> ./src (recommended)
5. API proxy: Backend URL if needed

Step 2: Generate Files in Order

ALWAYS generate files in this order to avoid import resolution issues:

1. package.json (defines project identity and deps)
2. tsconfig.json + tsconfig.node.json (TypeScript must resolve before config)
3. vite.config.ts (depends on tsconfig for path resolution)
4. index.html (entry point)
5. src/vite-env.d.ts (type declarations)
6. src/main.tsx or src/main.ts (application entry)
7. src/App.tsx / src/App.vue / src/App.svelte (root component)
8. .env.example (environment template)
9. .gitignore (version control)

Step 3: Install Dependencies

After generating files, run:

npm install

NEVER run npm install before all files are generated -- package.json must be complete first.

TypeScript Configuration

tsconfig.json Requirements

ALWAYS include these settings (non-negotiable for Vite):

Framework-specific JSX settings:

tsconfig.node.json (for vite.config.ts)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true
  },
  "include": ["vite.config.ts"]
}

Environment Variables Setup

.env.example Pattern

ALWAYS create .env.example with documented variables:

# Application
VITE_APP_TITLE=My Vite App
VITE_APP_VERSION=1.0.0

# API
VITE_API_BASE_URL=http://localhost:3000/api

TypeScript Env Types

ALWAYS extend ImportMetaEnv in src/vite-env.d.ts to match .env.example:

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

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_APP_VERSION: string
  readonly VITE_API_BASE_URL: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

.gitignore Env Rules

.env.local
.env.*.local
*.local

NEVER gitignore .env or .env.example -- these contain non-secret defaults and serve as documentation.

CSS Preprocessor Setup

CSS preprocessors require ONLY a package install -- NEVER a Vite plugin:

NEVER install vite-plugin-sass or similar -- Vite has built-in preprocessor support.

ALWAYS prefer sass-embedded over sass -- it runs Dart Sass in a separate process for better performance.

Version-Specific Configuration

Vite 8 (Oxc + Rolldown)

export default defineConfig({
  oxc: {
    jsx: {
      runtime: 'automatic',
    },
  },
  build: {
    rolldownOptions: {
      output: {
        manualChunks: undefined,
      },
    },
  },
})

Vite 6/7 (esbuild + Rollup)

export default defineConfig({
  esbuild: {
    jsx: 'automatic',
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: undefined,
      },
    },
  },
})

NEVER mix version-specific config keys -- using esbuild in Vite 8 triggers a deprecation warning and internal conversion.

Reference Links

• references/templates.md -- Complete file templates for React-TS, Vue-TS, Svelte-TS, and Vanilla-TS projects
• references/examples.md -- Full scaffold output per framework showing every generated file
• references/anti-patterns.md -- Common scaffolding mistakes and why they fail

Official Sources

• https://vite.dev/guide/
• https://vite.dev/config/
• https://vite.dev/guide/env-and-mode
• https://vite.dev/guide/features#typescript
• https://vite.dev/guide/features#css-pre-processors