Vite’s build process is unexpectedly stalling because the esbuild dependency, which Vite uses for its blazing-fast transpilation, is hitting a resource limit on your system.

Here are the most common reasons this happens and how to fix them:

1. Insufficient RAM

esbuild is incredibly fast because it loads your entire project into memory for processing. If your project is large or your machine has limited RAM, esbuild can start swapping to disk, which is orders of magnitude slower.

Diagnosis: Monitor your system’s RAM usage during a Vite build. On macOS, use Activity Monitor. On Linux, use htop or top. On Windows, use Task Manager. Look for sustained high RAM usage (over 80-90%) and significant swap/page file activity.

Fix:

  • Add more RAM: The most direct solution.
  • Reduce project size: Remove unused dependencies, optimize assets (images, fonts), and consider code splitting to reduce the amount of code esbuild needs to process at once.
  • Increase swap space (Linux/macOS): This is a workaround, not ideal. On Linux, you can use sudo fallocate -l 4G /swapfile and sudo mkswap /swapfile, then sudo swapon /swapfile. On macOS, this is more complex and involves creating a sparse file.

Why it works: By providing more physical RAM or more virtual memory through swap, you prevent esbuild from having to go to the much slower disk.

2. Antivirus Software Interference

Aggressive real-time scanning by antivirus or security software can significantly slow down file operations, including the many read/write operations Vite and esbuild perform during a build.

Diagnosis: Temporarily disable your antivirus software and run a Vite build. If it’s significantly faster, you’ve found your culprit.

Fix: Configure your antivirus software to exclude your project directory (node_modules and your source code folders) from real-time scanning. The exact steps vary by software, but generally involve going into settings and adding an exclusion path. For example, on Windows Defender, you’d go to "Virus & threat protection" -> "Virus & threat protection settings" -> "Add or exclude a file/folder".

Why it works: This prevents the antivirus from inspecting every single file operation, allowing Vite and esbuild to access and process files without constant overhead.

3. File System Performance Issues

On some systems, particularly network drives, cloud-synced folders (like Dropbox, Google Drive, OneDrive), or older/fragmented hard drives, file I/O can be a bottleneck.

Diagnosis: Try moving your project to a local, fast SSD. If the build speed improves dramatically, your original file system was the issue.

Fix:

  • Use a local SSD: Ensure your project resides on a fast, local solid-state drive.
  • Pause cloud sync during builds: If using cloud-synced folders, pause syncing before starting a build and resume afterward.
  • Optimize file system (Windows): Run defrag on traditional HDDs. For SSDs, ensure TRIM is enabled.

Why it works: A faster file system reduces the latency of reading source files and writing build artifacts, directly impacting build times.

4. Outdated esbuild or Node.js Version

While Vite pins its esbuild version, underlying system issues or conflicts with older Node.js versions can sometimes cause performance regressions.

Diagnosis: Check your Node.js version with node -v. Check your esbuild version within your package-lock.json or yarn.lock file.

Fix:

  • Update Node.js: Aim for the latest LTS version. Use a version manager like nvm (nvm install --lts, nvm use --lts) or fnm (fnm install --lts, fnm use --lts).
  • Reinstall node_modules: Delete your node_modules folder and package-lock.json (or yarn.lock) and run npm install (or yarn install). This ensures you have the latest compatible esbuild version.

Why it works: Newer versions of Node.js often have performance improvements in their V8 engine and I/O handling. A clean install of dependencies guarantees you’re using the intended and potentially optimized version of esbuild.

5. Large Number of Files in node_modules

Even though esbuild is smart, a massive node_modules directory can still contribute to overhead, especially if there are many small files or complex dependency trees.

Diagnosis: Run npm list --depth=0 or yarn list --depth=0 to see the top-level dependencies. If you have hundreds of direct dependencies, or if the total number of files in node_modules is exceptionally large (e.g., > 100,000 files), this could be a factor.

Fix:

  • Audit dependencies: Regularly review your package.json for unused or redundant dependencies. Tools like depcheck can help identify these.
  • Use Yarn PnP (Plug’n’Play) or pnpm: These package managers have different strategies for managing node_modules that can result in smaller disk footprints and potentially faster dependency resolution. For Yarn PnP, you’d remove node_modules and set "installCommand": "yarn install --immutable --inline-builds-from" in your package.json. For pnpm, install it globally (npm install -g pnpm), then run pnpm install.

Why it works: Yarn PnP and pnpm avoid the traditional, large node_modules structure. PnP uses a single .zip file for packages, and pnpm uses a content-addressable store and symlinks, both reducing disk space and potentially improving I/O for dependency resolution.

6. Insufficient ulimit (Linux/macOS)

On Unix-like systems, the ulimit setting controls the maximum number of open files a process can have. If this limit is too low, esbuild (or Node.js itself) might fail to open all necessary files, leading to errors or slowdowns.

Diagnosis: Run ulimit -n in your terminal. If the number is low (e.g., < 4096 or < 8192), it might be insufficient for large projects.

Fix: Increase the nofile limit. For a temporary session, run ulimit -n 65536. For a permanent change, you’ll need to edit /etc/security/limits.conf (on Linux) or use launchctl limit maxfiles (on macOS, often requires more complex configuration for persistent changes). Add lines like:

* soft nofile 65536
* hard nofile 65536

Then, reboot or log out/in.

Why it works: A higher ulimit allows Node.js and esbuild to keep more file descriptors open simultaneously, which is crucial when processing a large number of source files, modules, and dependencies during a build.

After addressing these, you’ll likely encounter issues with optimizing your static assets or configuring your CDN for faster delivery.

Want structured learning?

Take the full Vite course →