docs: clarify production build caching

[lilianakatrina684-a11y]

Summary

• clarify that cacheDir is mainly a dev cache and isn't reused as a persistent cache for production builds
• explain in the build guide that repeated �ite build runs are expected to transform and bundle the app again

Closes #19214

[santhiprakash]

Hi @lilianakatrina684-a11y — the dev-cache vs production-build clarification here looks useful.

While reading this paragraph I noticed an adjacent inaccuracy that would fit naturally into your edit if you're open to folding it in: the trailing sentence still reads

Default to .vite when no package.json is detected.

That doesn't match the actual resolution in resolveCacheDir (packages/vite/src/node/config.ts):

if (config.cacheDir) {
  cacheDir = path.resolve(resolvedRoot, config.cacheDir)
} else if (pkgDir) {
  cacheDir = path.join(pkgDir, `node_modules/.vite`)
} else {
  const nodeModulesDir = path.join(resolvedRoot, 'node_modules')
  cacheDir = fs.existsSync(nodeModulesDir)
    ? path.join(nodeModulesDir, `.vite`)
    : path.join(resolvedRoot, `.vite`)
}

So the bare .vite fallback only happens when neither a package.json nor a node_modules directory is detected — e.g. a Deno project with node_modules but no package.json still resolves to node_modules/.vite.

#23060 already corrected the JSDoc in config.ts to match this, but the user-facing docs here kept the older wording. Suggested replacement to match the corrected JSDoc:

Default to .vite when neither a package.json nor a node_modules directory is detected.

No worries if you'd rather keep this PR scoped to the build-caching clarification — just flagging it since it's the same paragraph. Happy to open a separate small PR if you prefer.

[github-actions]

The PR has been manually labeled as likely to be created by a bot, LLM, or agent, and will be automatically closed. This may be because the PR contains LLM-generated descriptions, does not follow the PR template, is overly verbose, or does not contain any fruitful interaction, which harms the review process. Please read our AI policy for more information.

If you believe this is a mistake, please reply to this comment and we will review it.