504 Outdated Optimize Dep in React Vite

Problem
When adding the js-big-decimal package to a React Vite project, you encounter a “504 (Outdated Optimize Dep)” error during compilation. This prevents the application from loading and typically occurs because Vite's dependency pre-bundling process fails to handle js-big-decimal correctly. The issue persists after installing the package and restarting the dev server.

---

Solution 1: Exclude Problematic Dependency

Add the problematic package to Vite’s optimizeDeps.exclude list in your vite.config.js:

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

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    exclude: ['js-big-decimal'] // Add exclusion here
  }
});

After updating the config:

1. Delete node_modules and .vite directory:

rm -rf node_modules .vite

2. Reinstall dependencies:

npm install

3. Restart the dev server:

npm run dev

Why this works

Vite pre-bundles dependencies during development. Some packages (like js-big-decimal) aren’t compatible with this process. Excluding them bypasses optimization errors.

---

Solution 2: Clear Cache and Reset Environment

If Solution 1 fails, reset Vite’s cache and dependencies:

# Clear Vite cache
rm -rf node_modules/.vite

# Clean npm/yarn cache
npm cache clean --force  # or yarn cache clean

# Reinstall dependencies
npm install

# Restart server
npm run dev

Note

Always shut down the dev server before executing these commands. Installing packages while the server is running can cause this error.

---

Additional Fixes

Try these if the error persists:

Fix Browser Cache

Perform a hard reload in your browser:

• Windows/Linux: Ctrl + Shift + R
• Mac: Cmd + Shift + R

Force Vite Cache Invalidation

Add --force flag to your dev script:

// package.json
"scripts": {
  "dev": "vite --force",
  // ...
}

Handle Multiple Projects

If working with multiple Vite projects, set unique cacheDir values to avoid conflicts:

// vite.config.js
export default defineConfig({
  cacheDir: './node_modules/.vite-myproject', // Unique name
});

---

Other Potential Causes

1. Invalid File Ownership (Docker/Linux):
   Ensure node_modules isn’t owned by root. Fix with:

   sudo chown -R $USER node_modules

2. Incorrect Node Version:
   Verify your Node version matches the engines requirement in package.json:

   {
     "engines": { 
       "node": ">=18" 
     }
   }

3. Long Folder Paths (Windows):
   Move the project to a shorter directory path (e.g., C:/dev/project).

4. System Limits (Linux):
   Increase open file limits by adding to /etc/systemd/system.conf:

   DefaultLimitNOFILE=65536

---

Confirmed Incompatibility

This issue stems from js-big-decimal’s architecture, which isn’t fully compatible with Vite's optimizer. Always exclude it from pre-bundling as shown in Solution 1.