Table of Contents
- Layer 1 — Reactive Variable Caching (Vue Reactivity System)
- Layer 2 — Computed Property Caching & Memoization
- Layer 3 — Composable-Level Data Caching
- Layer 4 — Nuxt Data Fetching Cache (
useFetch/useAsyncData) - Layer 5 — Server Route Caching with Nitro
- Layer 6 — Route-Level Cache Rules (
routeRules) - Layer 7 — HTTP & Browser Caching Headers
- Layer 8 — Pinia as a Client-Side Cache Store
- Quick Reference Cheat Sheet
Layer 1 — Reactive Variable Caching {#layer-1}
Before we talk about network caches, let's talk about reactivity overhead — because creating unnecessary deep reactive proxies is a silent performance killer in large Vue apps.
shallowRef and shallowReactive for large data
By default, ref() and reactive() deeply proxy every nested property. For large API responses, table rows, or chart datasets this is wasteful — you're paying to track changes you'll never make.
// ❌ Deep reactive — tracks every nested field on every item
const rows = ref<Row[]>([])
// ✅ Shallow reactive — triggers only when the array reference changes
const rows = shallowRef<Row[]>([])
async function loadPage(page: number) {
rows.value = await $fetch(`/api/rows?page=${page}`)
// Replacing the whole reference triggers reactivity cheaply
}
Rule: Use
shallowRefwhen you replace the whole object wholesale (pagination, API responses). Use deeprefonly when you mutate individual nested properties.
Object.freeze for truly static data
If your data never changes after fetch — config objects, lookup tables, static lists — freeze it entirely to opt out of Vue's proxy system:
const countries = shallowRef(Object.freeze(await $fetch('/api/countries')))
// Vue won't bother tracking any of this — zero reactivity overhead
v-once and v-memo in templates
<!-- Renders once and never re-renders, even if parent does -->
<HeavyStaticChart v-once :data="staticConfig" />
<!-- Re-renders only when userId changes -->
<UserCard
v-memo="[userId]"
:user="user"
:metadata="metadata"
/>
v-memo is especially powerful inside v-for loops with large stable lists.
Layer 2 — Computed Property Caching & Memoization {#layer-2}
Vue's computed() is itself a cache — it stores its last result and only recomputes when a tracked dependency changes. But there are patterns that break this guarantee.
Keep computed pure
// ❌ Breaks caching — Math.random() makes it non-deterministic
const discountedPrice = computed(() => price.value * Math.random())
// ✅ Pure — Vue can cache this safely
const discountedPrice = computed(() => price.value * 0.9)
Chain computed for granular invalidation
Instead of one giant computed with many dependencies, chain smaller ones. Each step caches independently:
const rawOrders = shallowRef<Order[]>([])
// Each computed caches its own slice of the pipeline
const paidOrders = computed(() =>
rawOrders.value.filter(o => o.status === 'paid')
)
const sortedOrders = computed(() =>
[...paidOrders.value].sort((a, b) => b.total - a.total)
)
const topTenOrders = computed(() => sortedOrders.value.slice(0, 10))
Changing rawOrders recomputes all three. But if only sortedOrders's sort key changes, only sortedOrders and topTenOrders invalidate.
Manual memoization for argument-based caching
computed doesn't accept arguments. For functions that take parameters, build a Map-based memo:
function useMemoized<A, R>(fn: (arg: A) => R) {
const cache = new Map<A, R>()
return (arg: A): R => {
if (cache.has(arg)) return cache.get(arg)!
const result = fn(arg)
cache.set(arg, result)
return result
}
}
// Usage in a composable
const getProductTax = useMemoized((productId: string) => {
return expensiveTaxCalculation(productId)
})
Layer 3 — Composable-Level Data Caching {#layer-3}
A composable defined outside the component instance acts as a singleton module-level cache — data persists across component mounts and unmounts.
// composables/useProductCatalog.ts
// Defined at module scope — shared across all consumers
const catalog = shallowRef<Product[]>([])
const lastFetched = ref<number | null>(null)
const TTL = 5 * 60 * 1000 // 5 minutes
export function useProductCatalog() {
async function fetchIfStale() {
const now = Date.now()
if (lastFetched.value && now - lastFetched.value < TTL) {
return // Still fresh, use the cache
}
catalog.value = await $fetch('/api/products')
lastFetched.value = now
}
return { catalog, fetchIfStale }
}
Any component calling useProductCatalog() shares the same catalog ref. The network request fires once and the result is reused until TTL expires.
Nuxt note: Be aware that module-level state is shared across all SSR requests on the server. Use
useState()oruseNuxtApp()for server-safe singleton state in Nuxt.
Layer 4 — Nuxt Data Fetching Cache (useFetch / useAsyncData) {#layer-4}
This is where Nuxt 4 brings the most significant improvements over Nuxt 3.
How the built-in cache works
useFetch and useAsyncData key-deduplicate requests. Multiple components calling the same key share one data, error, and status ref:
// components/UserProfile.vue AND components/UserBadge.vue
// Both call this — only ONE network request fires
const { data: user } = await useAsyncData('user-123', () =>
$fetch('/api/users/123')
)
In Nuxt 4, data fetched on the server is forwarded to the client in the payload, eliminating the double-fetch (server + hydration) problem entirely.
Reactive keys for dynamic data
// pages/users/[id].vue
const route = useRoute()
// computed key — Nuxt refetches when route.params.id changes
const userId = computed(() => `user-${route.params.id}`)
const { data: user } = await useAsyncData(
userId,
() => $fetch(`/api/users/${route.params.id}`)
)
In Nuxt 4, changing userId automatically purges the old cached data and triggers a fresh fetch.
getCachedData — custom client-side cache logic
This is the most underused feature. getCachedData lets you intercept the cache lookup and decide whether to return stale data or trigger a fresh request:
const nuxtApp = useNuxtApp()
const { data: posts } = await useAsyncData(
'blog-posts',
() => $fetch('/api/posts'),
{
getCachedData(key) {
// Return payload data if it already exists — skip the fetch
return nuxtApp.payload.data[key] ?? nuxtApp.static.data[key]
}
}
)
For a TTL-aware variant:
const CACHE_TTL = 60_000 // 1 minute
const cache = new Map<string, { data: unknown; ts: number }>()
const { data } = await useAsyncData('dashboard-stats', () =>
$fetch('/api/stats'), {
getCachedData(key) {
const entry = cache.get(key)
if (!entry) return undefined
if (Date.now() - entry.ts > CACHE_TTL) {
cache.delete(key)
return undefined
}
return entry.data
}
}
)
staleTime — the declarative TTL option
Nuxt 4 introduced staleTime as a first-class option, eliminating the need for manual getCachedData in most cases:
const { data } = await useFetch('/api/products', {
key: 'products-list',
staleTime: 5 * 60 * 1000 // Data is considered fresh for 5 minutes
})
Lazy loading and deferred fetching
// useLazyFetch — doesn't block navigation; shows loading state immediately
const { data, pending } = useLazyFetch('/api/recommendations', {
key: 'recommendations',
server: false // Only fetch on client — excludes from SSR payload
})
Abort signals for cancelled requests
Nuxt 4 exposes an AbortSignal in useAsyncData's handler, letting you cancel in-flight requests:
const { data, refresh } = await useAsyncData(
'live-feed',
(_nuxtApp, { signal }) => $fetch('/api/feed', { signal })
)
Layer 5 — Server Route Caching with Nitro {#layer-5}
Nuxt's server engine (Nitro) exposes two powerful caching primitives for API routes.
cachedEventHandler — cache entire route responses
// server/api/products.get.ts
import { cachedEventHandler } from 'nitropack/runtime'
import type { H3Event } from 'h3'
export default cachedEventHandler(
async (event) => {
const products = await db.product.findMany({ where: { active: true } })
return products
},
{
maxAge: 60 * 10, // Cache for 10 minutes
staleMaxAge: 60 * 60, // Serve stale for up to 1 hour while revalidating
swr: true, // Stale-While-Revalidate behaviour
getKey: (event: H3Event) => event.path, // Cache key per URL
varies: ['accept-language'] // Vary by header
}
)
cachedFunction — cache individual server functions
For shared logic called across multiple routes:
// server/utils/catalog.ts
import { defineCachedFunction } from 'nitropack/runtime'
export const getCatalog = defineCachedFunction(
async (category: string) => {
return db.product.findMany({ where: { category } })
},
{
maxAge: 60 * 30, // 30 minutes
name: 'catalog',
getKey: (category: string) => category
}
)
// server/api/electronics.get.ts
export default defineEventHandler(() => getCatalog('electronics'))
// server/api/apparel.get.ts
export default defineEventHandler(() => getCatalog('apparel'))
Cache storage backends
Configure the Nitro cache driver in nuxt.config.ts:
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
storage: {
cache: {
driver: 'redis',
url: process.env.REDIS_URL
}
}
}
})
Nitro's unstorage layer supports redis, fs, memory, cloudflare-kv, vercel-kv, and more — no code change required when switching backends.
Layer 6 — Route-Level Cache Rules (routeRules) {#layer-6}
routeRules lets you set rendering strategy and caching behaviour per route pattern directly in config — no middleware, no per-page logic.
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
// Marketing pages — full static, cached forever at CDN
'/': { prerender: true },
'/about': { prerender: true },
// Product pages — ISR: regenerate every 60 seconds
'/products/**': { isr: 60 },
// API responses — cached at CDN edge for 10 minutes
'/api/catalog/**': { cache: { maxAge: 60 * 10 } },
// Dashboard — always SSR, never cached
'/dashboard/**': { ssr: true, cache: false },
// User-specific pages — no caching, always fresh
'/account/**': { cache: false },
// Admin — redirect to login
'/admin/**': { redirect: '/login' }
}
})
Pro tip: Start with conservative TTLs and increase them over time. Stale pages are almost always better than slow pages, but you need to understand your data freshness requirements first.
Layer 7 — HTTP & Browser Caching Headers {#layer-7}
Nuxt and Nitro let you set fine-grained HTTP cache headers on any response.
// server/api/static-config.get.ts
export default defineEventHandler((event) => {
setResponseHeaders(event, {
'Cache-Control': 'public, max-age=3600, stale-while-revalidate=86400',
'CDN-Cache-Control': 'max-age=86400',
'Vary': 'Accept-Encoding'
})
return getStaticConfig()
})
Cache-Control directive cheat sheet
| Directive | Meaning |
|---|---|
public |
CDNs and proxies can cache this |
private |
Only the end browser should cache this |
max-age=N |
Fresh for N seconds |
s-maxage=N |
CDN-specific TTL (overrides max-age for proxies) |
stale-while-revalidate=N |
Serve stale for N seconds while refreshing in the background |
no-store |
Never cache (auth, sensitive data) |
immutable |
Asset will never change — skip revalidation entirely |
For Nuxt's static assets (JS, CSS, images), Nitro automatically appends content-hash fingerprints and sets immutable headers, so these are cached forever at the browser and CDN level.
Layer 8 — Pinia as a Client-Side Cache Store {#layer-8}
Pinia is more than state management — it's your application's runtime cache layer for data that needs to be shared and reused across many routes and components.
// stores/products.ts
import { defineStore } from 'pinia'
interface ProductCache {
data: Product[]
fetchedAt: number
}
export const useProductStore = defineStore('products', () => {
const cache = new Map<string, ProductCache>()
const TTL = 5 * 60 * 1000
function isStale(key: string): boolean {
const entry = cache.get(key)
if (!entry) return true
return Date.now() - entry.fetchedAt > TTL
}
async function fetchByCategory(category: string): Promise<Product[]> {
if (!isStale(category)) {
return cache.get(category)!.data
}
const data = await $fetch<Product[]>(`/api/products`, {
params: { category }
})
cache.set(category, { data, fetchedAt: Date.now() })
return data
}
function invalidate(category?: string) {
if (category) cache.delete(category)
else cache.clear()
}
return { fetchByCategory, invalidate }
})
Persisting Pinia state across page reloads
Use pinia-plugin-persistedstate for selective persistence:
// stores/userPreferences.ts
export const usePreferencesStore = defineStore('preferences', () => {
const theme = ref<'light' | 'dark'>('light')
const language = ref('en')
return { theme, language }
}, {
persist: {
storage: localStorage,
pick: ['theme', 'language'] // Only persist these fields
}
})
Quick Reference Cheat Sheet {#cheatsheet}
| Problem | Solution | Where |
|---|---|---|
| Large API array re-renders unnecessarily |
shallowRef instead of ref
|
Vue component / composable |
| Static template subtree re-renders | v-once |
Template |
| Expensive list items re-render | v-memo="[id]" |
Template v-for
|
| Derived state re-computed too often | Chain computed()
|
Component / composable |
| Same request fired by multiple components | Same useAsyncData key |
Nuxt pages |
| Data fetched on server AND client |
useAsyncData / useFetch (never raw $fetch in setup) |
Nuxt pages |
| Client navigates back, unnecessary refetch |
getCachedData or staleTime
|
useAsyncData options |
| API route hammered by many users |
cachedEventHandler with Nitro |
server/api/ |
| Shared server function called redundantly | defineCachedFunction |
server/utils/ |
| Marketing page slow to load |
prerender: true in routeRules
|
nuxt.config.ts |
| Product page needs periodic freshness |
isr: 60 in routeRules
|
nuxt.config.ts |
| State shared across components | Pinia store with TTL map | stores/ |
| Preferences survive page reload | pinia-plugin-persistedstate |
Pinia plugin |
Key Takeaways
Caching in Vue and Nuxt isn't a single decision — it's a strategy applied at every layer of the stack:
-
Reactivity layer: Reach for
shallowRefby default for data that's replaced wholesale. Reserve deep reactivity for objects you mutate in place. - Computed layer: Keep them pure, chain them for granular invalidation, and use manual memos for argument-based functions.
- Composable layer: Module-scope state is a free singleton cache — use it deliberately.
-
Data fetching layer:
useAsyncDatawithgetCachedDataorstaleTimegives you precise control over client-side request deduplication. -
Server layer:
cachedEventHandleranddefineCachedFunctionpush caching to the edge, absorbing load before it ever touches your database. -
Route layer:
routeRuleslets you declaratively assign the right rendering and caching strategy per page pattern. -
HTTP layer: Set
Cache-Controlheaders correctly to get CDN and browser caching without extra infrastructure. - State layer: Pinia with a TTL map is a battle-tested pattern for runtime client cache that survives navigation.
The right combination depends on your data's freshness requirements, your traffic patterns, and your deployment target. Start conservative, measure, and increase TTLs once you understand the shape of your data.
Found this useful? Follow me for more deep dives into Vue and Nuxt performance. Got a caching pattern you swear by that I missed? Drop it in the comments.