OpenAEC-Foundation/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?

| Version | Transform Engine | Bundler | Config Key | |---------|-----------------|---------|------------| | Vite 6/7 | esbuild | Rollup | esbuild | | Vite 8+ | Oxc | Rolldown | oxc |

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

| File | Purpose | Framework-Specific | |------|---------|-------------------| | vite.config.ts | Build tool configuration | Yes (plugin differs) | | tsconfig.json | TypeScript compiler options | Yes (JSX settings) | | tsconfig.node.json | Node-targeted TS config for vite.config.ts | No | | src/vite-env.d.ts | Vite client type declarations | No | | package.json | Dependencies and scripts | Yes (deps differ) | | index.html | Application entry point | Yes (root element, script src) | | src/main.tsx / src/main.ts | Application bootstrap | Yes (framework entry) | | src/App.tsx / src/App.vue / src/App.svelte | Root component | Yes | | .env.example | Environment variable template | No | | .gitignore | Version control exclusions | No |

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

| Framework | Plugin Package | Transform | When to Use | |-----------|---------------|-----------|-------------| | React | @vitejs/plugin-react | Babel | Need Babel plugins (relay, emotion, styled-components) | | React | @vitejs/plugin-react-swc | SWC | Default choice -- 20x faster than Babel | | Vue | @vitejs/plugin-vue | Vue compiler | ALWAYS for Vue SFC support | | Vue + JSX | @vitejs/plugin-vue-jsx | Babel | Only when using JSX in Vue | | Svelte | @sveltejs/vite-plugin-svelte | Svelte compiler | ALWAYS for Svelte | | Vanilla | None | Built-in | No framework plugin needed |

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):

| Setting | Value | Reason | |---------|-------|--------| | isolatedModules | true | Vite uses transpile-only transforms | | moduleResolution | "bundler" | Matches Vite's module resolution | | target | "ES2020" or higher | Vite targets modern browsers | | module | "ESNext" | Vite uses native ESM | | types | ["vite/client"] | Provides import.meta.env types | | skipLibCheck | true | Speeds up type checking |

Framework-specific JSX settings:

| Framework | jsx | jsxImportSource | |-----------|-------|-------------------| | React | "react-jsx" | "react" | | Vue | Not needed | Not needed | | Svelte | Not needed | Not needed | | Vanilla | Not needed | Not needed |

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:

| Preprocessor | Package to Install | File Extension | |-------------|-------------------|----------------| | Sass | sass-embedded (preferred) or sass | .scss / .sass | | Less | less | .less | | Stylus | stylus | .styl |

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