v4.0.2

What's Changed

• feat: export additional types for CacheTagRegistry and CacheType by @euaaaio in #105
• fix: check enabledForRequest when serving cached route by @dulnan in #107

New Contributors

• @euaaaio made their first contribution in #105

Full Changelog: v4.0.1...v4.0.2

v4.0.0

Breaking Changes

defineMultiCacheOptions import

Docs

defineMultiCacheOptions must be imported from nuxt-multi-cache/server-options (from before 'nuxt-multi-cache/dist/runtime/serverOptions').

multiCache.serverOptions.ts file location

Docs

The location of multiCache.serverOptions.ts is now being enforced as ~~/server/multiCache.serverOptions.ts for compatibility with Nuxt's new folder structure. This also makes sure that the types in this file are correct.

Require event in server utils

useDataCache, useRouteCache and useCDNHeaders require the H3Event as the second argument in a nitro context. Previously, these were not working without an event when used as server utils, causing them to return silently.

Unified "max age" Behaviour

Docs

Values and behaviour of max age arguments/props are now unified across all composables and components. The following numeric values are supported:

• <= -2: Same as -1 (permanent)
• -1: Cache permanently
• 0: Do not cache
• >= 1: Cache for the specified duration
• null or undefined: Cache permanently

Previously this was not handled the same across all caches, so the new unified behaviour can be a breaking change if you relied on e.g. 0 or -1 as a max age value, which in some cases had the opposite result.

Explicit max age in useCachedAsyncData

The useCachedAsyncData composable now requires the third argument (options), on which both clientMaxAge and serverMaxAge are now required. Previously, the options were not required and the default behaviour was to cache nothing.

New Features

Named max age

Docs

All arguments/props that accept a max age now also accept specific string literals such as 15m, 2h or 1d. In addition, the following time-relative strings are supported:

• next-hour: Cache until the next full hour
• midnight: Cache until midnight of today
• end-of-week: Cache until end of week (Sunday at 23:59:59)

For better readability you may also use permanent as a possible value, which is identical to -1.

useRouteCache((helper) => {
  helper.setMaxAge('midnight').setCacheable()
})

const { value, addToCache } = await useDataCache('users')
// ...
await addToCache(response, [], '1d')

useDataCacheCallback

Docs

A new composable and server util to cache the return value of a callback:

const { data } = await useAsyncData(() =>
  useDataCacheCallback(
    'current-time',
    (cache) => {
      if (cache) {
        cache.setMaxAge('10m').addTags('time')
      }

      return Date.now().toString(),
    },
    event,
  ),
)

This will call the callback only once, cache it and return the value of value. This is similar to useCachedAsyncData, but it can also be used in a Nitro context (event handlers, etc.).

New Composable: useComponentCache

Docs

It's now possible to add cache tags or define the max age of a cached component from within the component itself. The useComponentCache composable can be used in any component that is rendered inside <RenderCacheable>.

New Composable: useCacheAwareFetchInterceptor

Docs

This composable returns partial FetchOptions containing onRequest and onResponse interceptors. These interceptors can be used when making fetch requests to internal API routes. They will bubble the cacheability of the API request to the "main" request. That way you can e.g. "collect" cache tags from API routes and have them merged with the final SSR response.

Cache Tag Invalidation Improvements

Docs

There is a new cacheTagRegistry property available in the server options that can either be 'in-memory' or a custom implementation.

The Cache Tag Registry is used for quick lookups of which cache item keys need to be deleted when one or more cache tags are invalidated.

By default, when a cache tag is invalidated, the module needs to iterate over all cache items in all caches to determine which keys can be deleted. This is obviously very inefficient. The new Cache Tag Registry greatly improves performance for (very) large apps with potentially thousands of cache items. The built-in in-memory registry, as the name suggests, keeps track of this state in the memory of the app. This only works when the app runs in a single instance and if also using in-memory storage drivers (such as the LRU cache).

It's also possible to implement a custom registry. See the docs for more details.

Stale if Error

Docs

Both the data cache and the component cache now implement Stale if Error behaviour. In case of the data cache, a new staleValue property is returned in useDataCache, that contains the stale value. The component cache has a new stale-if-error prop. If set, stale cached markup may be returned if an error happens during rendering.

bubbleError

New bubbleError option on every cache in the server options. If true, any error that occurs while interacting with the storage driver will be rethrown so it can be handled by your app. For example, when setting bubbleError: true for the data cache, useDataCache will throw an error if the call to storage.getItem() or storage.setItem() throws an error. In case of route cache, setting it to true will result in the entire page showing a nitro error if e.g. your cache backend is down.

Bubble Cacheability

The component and data cache components/composables/utils now accept a bubbleCacheability prop/argument. If set, the cacheability (such as max age or cache tags) will "bubble" to the route cache or CDN headers.

For example, if you render a component like this:

<template>
  <RenderCacheable bubble-cacheability max-age="midnight" :cache-tags="['events']">
    <UpcomingEvents />
  </RenderCacheable>
</template>

Then on both the first and subsequent render from cache, the RenderCacheable component will bubble the max age and the cache tags for you. This is basically identical to:

useCDNHeaders(cdn => cdn.setNumeric('maxAge', 'midnight').addTags(['events'])
useRouteCache(cache => cache.setNumeric('maxAge', 'midnight').addTags(['events'])

With the only exception that maxAge and staleIfError will be recalculated when returning from cache. So for example, if the component was cached with a max age of 10 minutes and is served 7 minutes later, the max age set for the route cache or the CDN Headers will be 3 minutes; basically the remaining time until the component becomes stale.

Proper Types for API Routes

The module now generates proper types for its API purge/stats API endpoints.

Fixes

Runtime Config

Docs

The available runtime config and how to set them are now documented in the docs.

Usage with Nitro routeRules (e.g. swr)

If you prefer using Nitro's built in caching (such as swr [stale while revalidate]), you can now do so and use useDataCache and useCDNHeaders - they will work correctly for both the initial rendering and the subsequent "revalidate" rendering.

Usage of event.context

The module now adds anything state-related for the current request to event.context instead of event. This makes sure that request-state is not accidentally shared during internal requests (such as using useFetch() targeting a api route).

v3.4.0

What's Changed

Nuxt 4 compatibility (compatibilityVersion: 4)

The module should now be working when using compatibilityVersion: 4.

#77

New path for multiCache.serverOptions

To be in sync with the new folder structure of Nuxt 4 the server options file now defaults to <serverDir>/multiCache.serverOptions.ts which defaults to ~/server/multiCache.serverOptions.ts. The module will still look for the file in the app folder, however this will be removed in the next major release.

#84

Various

• fix: call handleRawCacheData in purgeTags event handler in #82
• fix: max age of 0 should mean uncacheable in useCachedAsyncData in #83

Full Changelog: v3.3.3...v3.4.0

v3.3.3

This release contains a bigger change in how cached routes are served, however because the previous change was partially broken, it is now released as a minor version to fix it for existing 3.3.x installs.

What's Changed

• feature: move serving of cached route to event handler in #73
• fix: add return type to useCachedAsyncData (#68) in #72
• fix: add server plugin when any feature is enabled (#69) in #71
• fix: setting headers via routeRules on cached routes (#64) in #66

Full Changelog: v3.3.1...v3.3.3

v3.3.1

The 3.3.0 release introduced a more robust way to hook into the nitro event lifecycle to handle route caching. Unfortunately it also introduced a bug where API routes were cached as well, even if not requested, if the page that made the API request was marked as cacheable.

What's Changed

• fix: don't set cache context on event.context (#64) by @dulnan in #65

Full Changelog: v3.3.0...v3.3.1

v3.3.0

What's Changed

• feat: refactor to use nitro hooks (#56) by @dulnan in #57
• feat: implement useCachedAsyncData by @dulnan in #58
• feat: implement "stale if error" and "stale while revalidate" by @dulnan in #61

Full Changelog: v3.2.0...v3.3.0

v3.2.0

What's Changed

• Cache management endpoints are excluded from enabledForRequest() #49
• Fix server response is never served from cache when using the fs driver #47
• New alterCachedHeaders option method to alter which headers are cached in route cache #30
• fix serverOptions types exports by @Applelo in #41
• fix: add consola to deps by @hpawa in #35
• fix(Route Cache): Filters set cookie header from page cache by @unluckynelson in #31
• Update overview/configuration.md doc by @valajan in #48
• Fix broken typedef export by @bgondy in #45
• Fix typo by @bgondy in #46
• chore(deps): update deps by @jpsc in #38

New Contributors

• @Applelo made their first contribution in #41
• @hpawa made their first contribution in #35
• @unluckynelson made their first contribution in #31
• @valajan made their first contribution in #48
• @bgondy made their first contribution in #45
• @jpsc made their first contribution in #38

Full Changelog: v3.1.1...v3.2.0

3.1.1

• Fix client side fatal exception in RenderCacheable due to changes in logging behavior
• Deprecate import of defineMultiCacheOptions from 'nuxt-multi-cache', as it results in the entire module being inlined in the server build. Instead it should now be imported like this, which will only import the helper method without any dependencies:
  import { defineMultiCacheOptions } from 'nuxt-multi-cache/dist/runtime/serverOptions'

3.1.0

• Uses setItemRaw for component and route cache to prevent JSON stringify/parse on large strings, which should improve performance
• New debug option for detailed logging. Setting it to false now only logs error messages (no more info/debug messages)
• On all caches, when a maxAge is defined for the cache item, it is additionally passed to the TransactionOptions of setItemRaw as the ttl property which is supported by the redis driver

v2.0.0 for Nuxt 3

Complete rewrite to support Nuxt 3. Most of the usage has changed due to the breaking changes from Nuxt 3.

The v2 releases are not compatible with Nuxt 2.

Migration guide from V1 to V2: https://nuxt-multi-cache.dulnan.net/overview/migrating-from-v1