Vite V8

Vite 8 Skill

Configure, migrate, and debug Vite 8 projects with the repo's preferred Vite-native patterns.

Before You Start

This skill focuses on the Vite 8 architecture shift, not generic bundler advice.

Known Issues This Skill Prevents

1. Broken builds from leaving rollupOptions in Vite 8 configs where rolldownOptions is needed 2. Outdated JS/TS transform setup from using esbuild instead of oxc 3. Plugin code checking stale ssr booleans instead of environment-aware APIs 4. HMR bugs from using deprecated handleHotUpdate patterns instead of hotUpdate 5. SSR/runtime confusion from older ssrLoadModule mental models instead of Module Runner 6. Performance regressions from missing hook filters in Rust↔JS plugin boundaries 7. Slow startup and request waterfalls from barrel files, missing warmup, or loose import resolution

Quick Start

Step 1: Start with a typed Vite 8 config

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    port: 5173,
  },
  build: {
    target: 'baseline-widely-available',
    rolldownOptions: {
      output: {
        manualChunks: undefined,
      },
    },
  },
});

Why this matters: Vite 8 is built around Rolldown/Oxc-era config and defaults. Starting from defineConfig with Vite 8 options avoids backporting old Rollup/esbuild assumptions into a new architecture.

Step 2: Prefer Vite 8 terminology in plugins and SSR code

import type { Plugin } from 'vite';

export function inspectEnvironment(): Plugin {
  return {
    name: 'inspect-environment',
    configEnvironment(name) {
      if (name === 'ssr') {
        return {
          resolve: {
            conditions: ['node'],
          },
        };
      }
    },
  };
}

Why this matters: Vite 8 leans on named environments and environment-aware plugin behavior. That is a better fit than older client-vs-SSR shortcuts.

Step 3: Use the correct one-shot commands

vite dev
vite build
vite build --ssr src/entry-server.ts
vite preview

Why this matters: These are the stable command surfaces agents and CI flows should target. Avoid inventing framework-specific abstractions unless the project already uses them.

Critical Rules

Always Do

• Use vite.config.ts with defineConfig for repo-facing Vite 8 work
• Prefer build.rolldownOptions over legacy build.rollupOptions
• Prefer oxc over esbuild for new Vite 8 transform configuration
• Use named environments when plugin or SSR behavior differs by runtime
• Use hook filters when writing performance-sensitive transform or resolveId plugins
• Reach for Module Runner concepts when debugging modern SSR/runtime execution
• Use explicit file extensions and review barrel files when performance work matters
• Keep Vite plugin code ESM-first

Never Do

• Never introduce new rollupOptions/esbuild examples as the preferred Vite 8 path
• Never treat handleHotUpdate as the forward-looking HMR hook in Vite 8
• Never assume a single client/SSR split is enough for all runtimes
• Never suggest CommonJS config as the default for new Vite work
• Never skip ssr.noExternal review when SSR dependencies misbehave

Common Mistakes

Wrong - legacy build config:

export default defineConfig({
  build: {
    rollupOptions: {
      external: ['react'],
    },
  },
  esbuild: {
    jsxInject: "import React from 'react'",
  },
});

Correct - Vite 8 config:

export default defineConfig({
  build: {
    rolldownOptions: {
      external: ['react'],
    },
  },
  oxc: {
    jsxInject: "import React from 'react'",
  },
});

Why: Vite 8 moved its preferred build and transform configuration surface to Rolldown and Oxc.

Wrong - stale HMR hook:

export default function plugin() {
  return {
    name: 'old-hmr',
    handleHotUpdate(ctx) {
      return ctx.modules;
    },
  };
}

Correct - environment-aware HMR:

export default function plugin() {
  return {
    name: 'env-hmr',
    hotUpdate(ctx) {
      return ctx.modules;
    },
  };
}

Why: hotUpdate is the environment-aware Vite 8 direction, while handleHotUpdate is legacy-oriented.

Known Issues Prevention

Bundled Resources

References

• Core config and CLI patterns → `references/core-config-reference.md`
• Environment-aware plugin authoring → `references/plugin-environment-reference.md`
• Build, SSR, and migration guidance → `references/build-ssr-migration-reference.md`
• Performance and dev-server heuristics → `references/performance-devserver-reference.md`
• Reference index → `references/README.md`

Configuration Reference

vite.config.ts

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    target: 'baseline-widely-available',
    rolldownOptions: {
      output: {
        chunkFileNames: 'assets/[name]-[hash].js',
      },
    },
  },
  oxc: {
    jsxInject: "import React from 'react'",
  },
  environments: {
    ssr: {
      resolve: {
        conditions: ['node'],
      },
    },
  },
  css: {
    lightningcss: {},
  },
});

Key settings:

• build.rolldownOptions: Preferred Vite 8 build customization surface
• oxc: Preferred JS/TS transform configuration surface in new Vite 8 examples
• environments: Use when runtime behavior differs across client/SSR/edge-like targets
• css.lightningcss: Reflects Vite 8's modern CSS processing direction
• server.warmup: Useful in large apps where cold-start waterfalls hit the same hot files repeatedly

Project Structure

my-app/
├── src/
├── index.html
├── vite.config.ts
├── package.json
└── tsconfig.json

Why this matters: Vite 8 still rewards simple, explicit project layout. Complexity should come from runtime environments and plugin boundaries, not from hiding the core config.

Performance heuristic: If startup feels bad, inspect import-graph shape before chasing exotic bundler flags. Barrel files, omitted extensions, and lack of warmup often matter more than another layer of config cleverness.

Common Patterns

Environment-aware plugin pattern

import type { Plugin } from 'vite';

export function envAwarePlugin(): Plugin {
  return {
    name: 'env-aware-plugin',
    transform: {
      filter: {
        id: /\.(ts|tsx)$/,
      },
      handler(code, id) {
        return {
          code,
          map: null,
        };
      },
    },
    configEnvironment(name) {
      if (name === 'ssr') {
        return {
          resolve: {
            conditions: ['node'],
          },
        };
      }
    },
  };
}

SSR build pattern

vite build
vite build --ssr src/entry-server.ts
vite preview

Module Runner mental model

// Pseudocode sketch
const mod = await moduleRunner.import('/src/entry-server.ts');

Use this model when modern Vite SSR debugging is really about runtime execution boundaries rather than plain bundling.

Dependencies

Required

Optional

Official Documentation

• Vite Docs
• LLM index
• Config Reference
• Plugin API
• Build Guide
• SSR Guide
• Environment API

Troubleshooting

Old config keys no longer feel right

Symptoms: A config works but reads like pre-Vite-8 code, or new options are not behaving as expected.

Solution:

build: {
  rolldownOptions: {},
}

oxc: {}

SSR runtime behavior is unclear

Symptoms: The bundle builds, but runtime execution differs by environment or platform.

Solution: Review environments, this.environment, Module Runner expectations, and ssr.noExternal before changing unrelated bundler settings.

Plugin hook work feels slow or noisy

Symptoms: Custom plugins add overhead in dev or build.

Solution: Use hook filters and narrow matching patterns so only relevant files cross the Rust↔JS boundary.

Setup Checklist

Before using this skill, verify:

• [ ] vite is on a Vite 8 release line
• [ ] Node satisfies Vite 8 runtime requirements
• [ ] vite.config.ts is ESM/TypeScript-first
• [ ] Legacy rollupOptions / esbuild usage has been reviewed
• [ ] Environment-specific behavior is modeled explicitly when SSR/edge runtimes are involved

Vite 8 Skill

Configure, migrate, and debug Vite 8 projects with Rolldown, Oxc, and environment-aware plugin patterns.

What This Skill Does

Provides expert assistance for Vite 8 projects, from vite.config.ts setup through plugin authoring, environment-aware runtime configuration, and Rolldown/Oxc migration. It focuses on the real Vite 8 architecture shift rather than generic bundler advice.

Core Capabilities

• Configure vite.config.ts with Vite 8-era options and conventions
• Migrate legacy Rollup/esbuild-flavored configs to Rolldown/Oxc surfaces
• Author Vite plugins with named environments, hook filters, and environment-aware HMR flows
• Debug SSR/build/runtime issues using Vite 8 mental models such as Module Runner and isolated environments
• Improve production build behavior while keeping dev/build assumptions aligned
• Tune startup and dev-server behavior with warmup, config-loader, and dependency-graph heuristics

Auto-Trigger Keywords

Primary Keywords

• vite
• vite 8
• vite.config.ts
• rolldownOptions
• oxc
• environments
• module runner
• hotUpdate

Secondary Keywords

• lightning css
• ssr.noExternal
• configEnvironment
• this.environment
• hook filters
• rolldown migration
• build target

Error-Based Keywords

• "rollupOptions is not behaving as expected"
• "esbuild config is deprecated"
• "handleHotUpdate"
• "ssrLoadModule"
• "default import from cjs behaves differently"

Known Issues Prevention

When to Use

Use This Skill For

• Creating or fixing vite.config.ts
• Migrating Vite projects to Vite 8 terminology and config surfaces
• Writing or reviewing Vite plugins
• Troubleshooting SSR/runtime/environment-specific behavior
• Improving build config without falling back to outdated Rollup guidance

Don't Use This Skill For

• Framework-only issues that are actually owned by Next.js/Nuxt/etc internals
• Vitest-specific testing workflows where vitest-v4 is the better fit

Version Policy

[!NOTE]

This skill targets Vite 8+. It assumes the Rolldown/Oxc-era config surface and modern environment APIs. If the repo is intentionally pinned to an older Vite line, verify version-specific support before applying the migration guidance here.

Quick Usage

# Start dev server
npx vite dev

# Production build
npx vite build

# SSR build
npx vite build --ssr src/entry-server.ts

# Preview production output
npx vite preview

Token Efficiency

Reference Documentation

For deeper guidance on the most failure-prone areas, see:

See the References Index for navigation.

File Structure

vite-v8/
├── SKILL.md        # Quick-start patterns, critical rules, and practical guidance
├── README.md       # This file - discovery and quick reference
└── references/
    ├── README.md                          # Reference index
    ├── core-config-reference.md          # Config and CLI patterns
    ├── plugin-environment-reference.md   # Environment-aware plugin authoring
    ├── build-ssr-migration-reference.md  # Build, SSR, and migration guidance
    └── performance-devserver-reference.md # Startup, dev-server, and scaling guidance

Dependencies

Official Documentation

• Vite Docs
• LLM Index
• Config Reference
• Plugin API
• Build Guide
• SSR Guide
• Environment API

Related Skills

• vitest-v4 - Vitest workflows when the problem is test-runner specific rather than Vite build/runtime specific
• github-actions - CI workflow authoring when Vite builds and previews run in GitHub Actions

---

License: MIT

Vite 8 Build, SSR, and Migration Reference

Vite 8 unifies more of the dev/build/runtime story around Rolldown and environment-aware execution.

Rolldown and Oxc Migration

The main migration points are:

• build.rollupOptions → build.rolldownOptions
• esbuild → oxc
• legacy HMR/plugin assumptions → environment-aware hooks and filters

Also watch for older config snippets that still talk about esbuild CSS minification or Rollup-specific extension points as the preferred path. In Vite 8, those examples are often historically accurate but strategically wrong.

SSR Guidance

SSR issues in Vite 8 are often runtime-boundary issues rather than plain bundling issues. Review:

• environments
• this.environment
• ssr.noExternal
• Module Runner concepts

Module Runner

Modern Vite SSR/runtime execution is better explained through Module Runner mental models than older ssrLoadModule-centric guidance.

When SSR debugging feels like “the bundle built but runtime is wrong,” it is often a Module Runner or environment-boundary problem rather than a bundling one.

CSS and Build Output

Lightning CSS is the modern default direction, and build behavior should be validated under the same Vite 8 assumptions used in dev.

Rollup Hook Caveat

Some Rollup hooks behave differently under Rolldown-era execution, especially assumptions about parallelism or dev-only parsing behavior. Do not assume every historical Rollup performance trick still maps 1:1.

Production Checklist

• Run vite build
• Run vite build --ssr <entry> when SSR applies
• Run vite preview
• Validate runtime-specific behavior after externalization decisions

Vite 8 Core Config Reference

Vite 8 config should reflect the Rolldown/Oxc architecture rather than older Rollup/esbuild-era defaults.

Core CLI

• vite dev
• vite build
• vite build --ssr <entry>
• vite preview

Config Loading

Vite 8 supports config loading modes such as bundle, runner, and native via --configLoader when debugging config execution behavior.

Preferred Config Surface

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rolldownOptions: {
      external: ['react'],
    },
  },
  oxc: {
    jsxInject: "import React from 'react'",
  },
  environments: {
    ssr: {},
  },
});

Migration Notes

• Prefer build.rolldownOptions over build.rollupOptions
• Prefer oxc over esbuild in new Vite 8 guidance
• Default build targeting follows the Baseline Widely Available browser target
• Lightning CSS is part of the modern Vite 8 direction for CSS processing/minification
• Node.js must satisfy the Vite 8 runtime floor (20.19+ or 22.12+)
• build.commonjsOptions is effectively a no-op in the Rolldown era and should not be treated as a first-line tuning lever

CommonJS Interop Note

Vite 8 tightened default-import behavior for CommonJS modules. When a CJS import suddenly behaves differently across older and newer examples, treat that as a real migration boundary rather than a random build bug.

Environment Configuration

Use environments when runtime behavior differs meaningfully between client, SSR, edge, or custom execution targets.

Vite v8 Performance and Dev Server Reference

Many Vite performance problems are graph-shape problems, not bundler-flag problems.

First Things to Check

1. Barrel files that fan out a large import graph 2. Omitted file extensions that force more filesystem work 3. Hot files that would benefit from server.warmup 4. Config-loading failures better solved with --configLoader runner

Warmup

Use server.warmup for files that are predictably hit during first-load waterfalls. This is especially useful in large applications where startup repeatedly touches the same routes, layouts, or plugin-heavy modules.

Barrel File Warning

Barrel exports (index.ts re-export hubs) are convenient but can explode the graph surface Vite has to traverse. Before micro-tuning bundler config, inspect whether one broad barrel import is pulling in far more code than the page or plugin actually needs.

Explicit Extensions

Explicit .ts, .tsx, .js, or .jsx imports can reduce resolution overhead and ambiguity in large repos.

Config Loader Heuristic

If config execution behaves strangely in a monorepo or advanced TS setup, try vite --configLoader runner before concluding that the config itself is broken.

Forward-Looking Note

Vite's full-bundle direction exists to reduce network overhead in very large codebases. Treat this as a clue that graph shape and startup waterfalls are first-class performance concerns in modern Vite, not afterthoughts.

Vite 8 Plugin Environment Reference

Vite 8 plugin authoring is increasingly environment-aware.

Current Environment Access

Use this.environment inside plugin hooks when behavior depends on the active runtime.

This is a real architectural shift away from simplistic ssr booleans. When a plugin touches multiple runtimes, environment identity should drive the design.

Environment-Specific Config

export default function myPlugin() {
  return {
    name: 'my-plugin',
    configEnvironment(name) {
      if (name === 'ssr') {
        return {
          resolve: {
            conditions: ['node'],
          },
        };
      }
    },
  };
}

HMR Direction

Prefer hotUpdate for modern, environment-aware HMR customization rather than building new logic around handleHotUpdate.

Hook Filters

Use hook filters to reduce unnecessary cross-runtime work when plugins run across Rust↔JS boundaries.

transform: {
  filter: {
    id: /\.(ts|tsx)$/,
  },
  handler(code, id) {
    return { code, map: null };
  },
}

Shared Build Plugins

When a plugin must be shared across environments during build, review sharedDuringBuild or related builder-sharing settings instead of assuming old single-pipeline behavior.

Rolldown Detection

When debugging plugin compatibility, this.meta.rolldownVersion can help detect whether the plugin is running under the new engine assumptions.

Module Type Hint

If a load or transform hook turns non-JS content into executable JS, return moduleType: 'js' so Rolldown can classify it correctly.

Vite 8 Skill References

Use these references when the main SKILL.md is not enough:

Suggested Reading Order

• Fixing config drift? Start with core-config-reference.md
• Writing or debugging plugins? Start with plugin-environment-reference.md
• Handling build/SSR migration? Start with build-ssr-migration-reference.md
• Improving startup or dev-server feel? Start with performance-devserver-reference.md

Official Sources

• Vite Docs
• LLM Index
• Environment API