Ever been stuck debugging a failed build, only to discover that it’s because your favorite tool—like Vite—was mysteriously “not found”? If you’ve encountered this frustration, chances are you were running your build with --production=true. Let me walk you through why this happens, how to fix it, and how to avoid this headache in the future.

---

What Happens When You Use --production=true?

When you use --production=true (or a similar flag in your build process), it triggers production mode. This mode is designed for deployment and comes with key optimizations:

• Only dependencies are installed (skipping devDependencies).

• Build tools like Webpack, Vite, or Rollup (usually listed in devDependencies) are excluded.

• The goal is to reduce the size of node_modules and improve runtime performance.

However, this setup can backfire when critical build tools are missing in production, causing errors like:

Error: vite not found

---

Why Does This Happen?

In most projects, tools like Vite, Webpack, or other build systems are added to devDependencies in package.json:

"devDependencies": {
  "vite": "^4.0.0",
  "eslint": "^8.0.0"
}

This makes sense because these tools are only needed for development and the build process—not at runtime. But when you run --production=true, only the dependencies section is installed, so devDependencies (including Vite) are skipped. This leads to a failed build.

---

How to Fix It

1. Install All Dependencies (Including devDependencies)

You can force the installation of both dependencies and devDependencies during your production build:

npm install --production=false

This ensures that all required tools are available for the build process.

---

2. Move Build Tools to dependencies

If Vite (or any other build tool) is essential for the build process, move it from devDependencies to dependencies:

"dependencies": {
  "vite": "^4.0.0"
}

This ensures the tool is always installed, even in production mode. However, this approach can increase the size of your node_modules folder in production deployments.

---

3. Run Builds in Development Mode

If you only need the build process to work, set the environment to development when running the build:

NODE_ENV=development npm install && npm run build

This installs all dependencies, including those in devDependencies.

---

4. Use CI/CD to Handle Dependencies Properly

In a CI/CD pipeline, make sure your commands include all dependencies before the build:

npm install --production=false && npm run build

This ensures that the build process has everything it needs while your final deployment can still strip out unnecessary dependencies.

---

Best Practices to Avoid Build Failures

1. Audit Your package.json Structure

   • Use dependencies for libraries and tools required at runtime and for building in production.

   • Use devDependencies for tools only needed during development or testing.

2. Separate Build and Runtime Steps in CI/CD

   • Install all dependencies for the build step.

   • Prune unnecessary dependencies for the final deployment:

       npm prune --production
     

3. Explicitly Handle --production Flags
   If you rely on custom scripts, make sure they account for missing devDependencies. For example, use tools like minimist to handle flags:

    const args = require('minimist')(process.argv.slice(2));
    if (args.production) {
      console.log("Running in production mode");
    }
   

4. Lock Dependencies with npm ci
   Use npm ci in CI/CD pipelines to ensure a clean and reproducible dependency installation:

    npm ci && npm run build
   

---

TL;DR: The Fix for Your Build Woes

If your build is failing due to tools like Vite missing in production mode, here’s a quick checklist:

• Install all dependencies with npm install --production=false.

• Move essential build tools from devDependencies to dependencies.

• Ensure your CI/CD pipeline installs everything before the build process.

• Separate the build and runtime installation steps for cleaner deployments.

---

Final Thoughts

The --production=true flag is a powerful way to optimize deployments, but it comes with pitfalls when build tools live in devDependencies. By understanding how this flag works and carefully managing your package.json, you can avoid hours of frustration and keep your builds running smoothly.

Have your own --production=true horror story? Share it in the comments! Let’s commiserate—and celebrate the fixes—together.