OpenAEC-Foundation/vite-errors-build

vite-errors-build

Quick Reference: Build Error Diagnostic Table

| Symptom | Cause | Fix | |---------|-------|-----| | Could not resolve './module' | Unresolved import path | Check file exists, verify resolve.alias config, ensure extensions match resolve.extensions | | Circular dependency detected | Modules import each other | Refactor shared logic into a third module; use dynamic import() to break the cycle | | [vite]: Rollup failed to resolve import | Bare import not in node_modules | Run npm install, verify package name spelling, check optimizeDeps.include | | Warning: Some chunks are larger than 500 KiB | Chunk exceeds build.chunkSizeWarningLimit | Code-split with dynamic imports, increase limit, or use build.rolldownOptions.output.manualChunks | | build.target: Unexpected token | Syntax too modern for target browsers | Lower build.target (e.g., 'es2020') or add @vitejs/plugin-legacy | | CSS minification error (v8) | Lightning CSS cannot parse CSS | Set build.cssMinify: 'esbuild' as fallback; fix invalid CSS syntax | | Sourcemap is likely to be incorrect | Plugin transforms without sourcemap | Set build.sourcemap: false or fix plugin to emit sourcemaps | | Missing "name" option for UMD export | Library mode UMD without name | Add build.lib.name: 'MyLib' for UMD/IIFE formats | | build.rollupOptions is deprecated (v8) | Using Rollup config key in v8 | Rename to build.rolldownOptions | | BundleError thrown (v8) | Build API throws structured error | Catch with e.errors array iteration (see v8 Error Handling) | | terser not found | Terser not installed | Run npm install -D terser; or switch to build.minify: 'oxc' (v8 default) | | esbuild not found (v8) | esbuild no longer bundled in v8 | Run npm install -D esbuild; or migrate to oxc config | | Could not load content for ... (sourcemap) | Sourcemap references missing source | Set build.sourcemap: 'hidden' or ensure sources exist | | vite:preloadError in browser | Dynamic import chunk missing after deploy | Listen for vite:preloadError event, trigger page reload | | emptyOutDir: outDir is not inside root | Safety check prevents deletion | Pass build.emptyOutDir: true explicitly to override | | assetsDir is ignored in lib mode | Library mode ignores build.assetsDir | ALWAYS use flat output or build.rolldownOptions.output.assetFileNames in lib mode | | moduleType not set (v8 plugin) | Plugin transforms non-JS without declaring type | Add moduleType: 'js' in plugin load/transform hook return |

---

Critical Warnings

NEVER ignore chunk size warnings in production -- they indicate bundles that degrade page load performance. ALWAYS code-split large vendor dependencies with dynamic imports.

NEVER set build.sourcemap: true in production without understanding the security implications -- sourcemaps expose original source code. Use 'hidden' to generate maps without embedding references.

NEVER use build.rollupOptions in Vite 8 -- it is deprecated and will be removed. ALWAYS use build.rolldownOptions instead.

ALWAYS install terser separately when using build.minify: 'terser' -- Vite does NOT bundle terser. In v8, esbuild is also not bundled.

ALWAYS handle vite:preloadError in SPAs to gracefully recover from stale chunk references after deployment.

---

Decision Tree: Build Failure Diagnosis

Build fails?
  |
  +-- Error message contains "resolve"?
  |     +-- Bare import? --> Check node_modules, run npm install
  |     +-- Relative import? --> Verify file path, check resolve.alias
  |     +-- TypeScript path? --> Enable resolve.tsconfigPaths or add alias
  |
  +-- Error message contains "chunk" or "size"?
  |     +-- Warning only? --> Split code or raise build.chunkSizeWarningLimit
  |     +-- Build fails? --> Check build.rolldownOptions.output config
  |
  +-- Error message contains "CSS"?
  |     +-- Lightning CSS error (v8)? --> Fallback to build.cssMinify: 'esbuild'
  |     +-- Preprocessor error? --> Check sass/less/stylus installed
  |     +-- PostCSS error? --> Verify postcss config, check plugin versions
  |
  +-- Error message contains "minify"?
  |     +-- terser not found? --> npm install -D terser
  |     +-- esbuild not found (v8)? --> npm install -D esbuild or use oxc
  |     +-- oxc error? --> Check oxc config syntax, report upstream if bug
  |
  +-- Error message contains "target"?
  |     +-- Syntax error in output? --> Lower build.target
  |     +-- CSS feature unsupported? --> Set build.cssTarget separately
  |
  +-- Library mode error?
  |     +-- Missing name? --> Add build.lib.name for UMD/IIFE
  |     +-- Missing externals? --> Add to build.rolldownOptions.external
  |     +-- CSS filename? --> Use build.lib.cssFileName
  |
  +-- v8 migration error?
        +-- rollupOptions? --> Rename to rolldownOptions
        +-- esbuild config? --> Rename to oxc config
        +-- moduleType error? --> Add moduleType: 'js' in plugin
        +-- BundleError? --> Catch e.errors array

---

v8 BundleError Handling

Vite 8 throws a BundleError from the build() API instead of raw errors. ALWAYS use structured error handling:

import { build } from 'vite'

try {
  await build()
} catch (e) {
  if (e.errors) {
    // BundleError: iterate structured error array
    for (const error of e.errors) {
      console.error(`[${error.code}] ${error.message}`)
      if (error.frame) console.error(error.frame)
      if (error.loc) {
        console.error(`  at ${error.loc.file}:${error.loc.line}:${error.loc.column}`)
      }
    }
  } else {
    // Fallback for non-BundleError
    throw e
  }
}

---

Chunk Size Optimization

Default warning limit: 500 KiB (uncompressed). To fix large chunks:

// Option 1: Dynamic imports for route-level code splitting
const AdminPanel = () => import('./views/AdminPanel.vue')

// Option 2: Manual chunk splitting (v8 with Rolldown)
export default defineConfig({
  build: {
    rolldownOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            if (id.includes('lodash')) return 'vendor-lodash'
            if (id.includes('chart.js')) return 'vendor-charts'
            return 'vendor'
          }
        },
      },
    },
  },
})

// Option 3: Raise the limit (last resort)
export default defineConfig({
  build: {
    chunkSizeWarningLimit: 1000, // KiB
  },
})

NEVER raise chunkSizeWarningLimit without first attempting code splitting -- the warning exists to protect user experience.

---

vite:preloadError Recovery

After deployment, users with cached pages may request chunks that no longer exist. ALWAYS add this handler to SPA entry points:

// main.ts -- add BEFORE app initialization
window.addEventListener('vite:preloadError', (event) => {
  event.preventDefault()
  // Reload to fetch updated HTML with new chunk references
  window.location.reload()
})

---

emptyOutDir Safety

Vite refuses to empty outDir if it is outside the project root:

// outDir outside root triggers safety warning
export default defineConfig({
  build: {
    outDir: '../dist',           // Outside root -- Vite warns and skips
    emptyOutDir: true,           // Explicit override required
  },
})

ALWAYS set build.emptyOutDir: true explicitly when outDir is outside root. Vite adds this safety check to prevent accidental deletion of unrelated directories.

---

Version-Specific Error Patterns

| Error Pattern | Vite 6 | Vite 7 | Vite 8 | |--------------|--------|--------|--------| | Bundler config key | build.rollupOptions | build.rollupOptions | build.rolldownOptions | | Transform config | esbuild | esbuild | oxc | | Default minifier | esbuild | esbuild | oxc | | CSS minifier default | esbuild | esbuild | Lightning CSS | | build.target default | 'modules' | 'baseline-widely-available' | 'baseline-widely-available' | | Build error type | Raw error | Raw error | BundleError | | Plugin moduleType | Not required | Not required | Required for non-JS | | Node.js minimum | 18+ | 20.19+ / 22.12+ | 20.19+ / 22.12+ |

---

Reference Links

• references/error-catalog.md -- Complete build error catalog with symptom, cause, fix for every known pattern
• references/examples.md -- Reproducible error scenarios with step-by-step solutions
• references/anti-patterns.md -- Build configuration mistakes to avoid

Official Sources

• https://vite.dev/guide/build
• https://vite.dev/config/build-options
• https://vite.dev/guide/migration
• https://vite.dev/guide/dep-pre-bundling