Nuxt · NUXT0093

Keep Vue build inputs inside the Nuxt build cache key

Finds local files outside every hashed srcDir that the Vue build still consumes, such as a root lib/ imported from app/, when experimental.buildCache is enabled.
NUXT0093vite-doctor/nuxtcachewarnSuggestion

Run this rule

pnpm nuxt doctor --rules nuxt/config/no-unhashed-build-cache-input

Why it matters

experimental.buildCache restores the cached Vue client and SSR bundles when its key matches, and Nitro rebuilds the server either way. The key hashes each local layer's srcDir (minus server/, public/ and node_modules), a few root files (package.json, lockfiles, tsconfig.json, .npmrc, .nuxtrc) and the raw nuxt.config. With the Nuxt 4 app/ layout, srcDir is app/, so files the app imports from ~~/lib, a root utils/ or a local module's runtime plugin are not part of the key. A commit that only changes them restores stale client and SSR bundles next to a fresh server. Nuxt 4.6.2 and older also leave shared/ out of the key; nuxt/nuxt#36704 adds it on main, so Doctor reports shared/ only for those versions. Doctor reports one diagnostic per unhashed directory and skips type-only imports, server/, public/, node_modules and paths another local layer's srcDir covers.

Move code only the app uses under app/. Otherwise add the directory to the CI cache key you use for node_modules/.cache/nuxt/builds, or turn off experimental.buildCache. For shared/, upgrading to a Nuxt release with nuxt/nuxt#36704 also fixes it.

Example

Keep app-only helpers inside app/

Before

// nuxt.config.ts
export default defineNuxtConfig({ experimental: { buildCache: true } })

// app/utils/alerts.ts
export { formatAlert } from '~~/lib/format-alert'

After

// nuxt.config.ts
export default defineNuxtConfig({ experimental: { buildCache: true } })

// app/utils/alerts.ts
export { formatAlert } from '~/lib/format-alert'
Copyright © 2026