Unclear Documentation: Production vs Development Caching Behavior

[CodySchaaf]

Documentation is

• Missing
• Outdated
• Confusing
• Not sure?

Explain in Detail

The documentation clearly explains dependency pre-bundling and caching behavior in development mode, but is unclear about what caching behavior (if any) should be expected during production builds.

Currently, we can observe that:

• Development mode uses the .vite cache directory for dependency pre-bundling
• Production builds appear to rebuild/transform all modules each time
• The cacheDir config option exists but its impact on production builds is not documented

This creates uncertainty when:

• Planning CI/CD pipelines
• Trying to optimize build times
• Deciding whether to pursue other optimization strategies

Your Suggestion for Changes

Add a section in the Production build documentation that explicitly describes:

1. Expected caching behavior in production builds
2. How caching differs between development and production
3. Whether any caching between production builds is possible/intended
4. If no caching is intended for production, explain the reasoning

This would help teams better understand what to expect and how to optimize their build processes.

Reproduction

No response

Steps to reproduce

1. Create new Vite project (npm create vite@latest)
2. Run production build: npm run build
3. Run production build again without changes
4. Observe that all modules are transformed again
5. Check .vite directory - no cached artifacts from production builds

The behavior itself works, but its documentation is unclear about whether this is expected, or can be improved.

[lilianakatrina684-a11y]

Hi! I’d like to work on this documentation update and open a small PR clarifying how cacheDir and dependency caching differ between dev and production builds. I’ll keep the change focused on the existing build docs.

[LeonxLJX]

I'd like to take this one.

Reading the issue, this looks like a documentation-clarity gap rather than a code defect: the current page doesn't give readers enough to self-diagnose, which is why it surfaces here as an issue instead of being answered by the docs.

My plan: locate the relevant section, confirm the described behavior against the current source (so the docs match what the code actually does today, not what it did when the page was written), then tighten the wording and add the missing piece. I'll also scan neighboring pages for the same inconsistency, otherwise the fix just relocates the confusion.

One thing I'd like to confirm before writing: would you prefer a minimal correction scoped to this page, or should I also cross-link it from the related guides if the same gap shows up there?

(claiming via @LeonxLJX)