Caching

Overview

The Storefront Application uses hybrid rendering, an approach that combines Server-Side Rendering (SSR), Single Page Application (SPA), and Static Site Generation (SSG). Depending on the page content, the most appropriate rendering mode is automatically chosen.

The Storefront Application relies heavily on server-side caching. This aims to reduce the load on the server and minimize the time and resources required to generate dynamic content for each user request. By caching the results of expensive API calls, or entire rendered pages, server-side caching optimizes response times, decreases server processing overhead, and ultimately delivers a smoother and more efficient user experience.

Before You Start: Key Concepts

Familiarize yourself with the following concepts for a better understanding of caching:

Hybrid Rendering

Hybrid rendering allows different caching rules per route using Route Rules and intelligently decides how the server should respond to a new request on a given URL. Nuxt 3 includes native support for route rules and hybrid rendering.

The Nuxt server of the Storefront Application automatically registers corresponding middleware and wraps routes with cache handlers using the Storefront SDK's Cache setup, which is built upon the Nitro caching layer. Check the Nuxt documentation for any changes or additions.

Route Rules

Nuxt, specifically its underlying web engine Nitro, allows the addition of logic at the top level of the nuxt.config.ts configuration. This is useful for redirecting, proxying, caching, and adding headers to all or specific routes.

By default, Nuxt utilizes its in-memory cache, powered by the Nitro Caching API, for internal data storage. This includes data managed by routeRules, unless otherwise specified (for instance, with server-side rendered page responses). However, relying solely on in-memory caching for page responses can significantly increase the application's memory footprint at runtime.

To address this, the Storefront Application's default configuration prioritizes efficient resource utilization. It achieves this by not caching rendered page responses within the application's memory. Instead, it offloads this responsibility, leveraging external caching mechanisms for optimal performance and reduced memory consumption. More details are available in the Default Configuration section below.

For more in-depth details on how routeRules work, check the Nitro — Route Rules documentation.

Implementation

Page Caching in Storefront Application

Default configuration

The Storefront Application only utilizes the HTTP Cache-Control header. This header instructs external caching mechanisms, such as web browsers, shared proxies, and Content Delivery Networks, to cache the rendered page responses on their end. This external caching strategy effectively reduces the Storefront Application's memory requirements while still ensuring fast and responsive content delivery to users.

The Storefront Application implements a robust page caching strategy using routeRules. These rules are set up within the nuxt.config.ts file. By default, caching is broadly enabled for most pages via the /** path, with a maxAge of 10 minutes, ensuring a fast and responsive experience across your site. Crucially, this default configuration leverages headersOnly: true, meaning the application only applies cache headers to responses, relying entirely on external caches (like browsers, proxies, and CDNs) to store and manage the content.

However, to maintain data accuracy and provide a personalized user experience, the caching for specific API endpoints and user-specific routes such as /api/**, /wishlist, /basket, /checkout, /signin, and /account/**, is disabled by cache: false. This selective caching approach ensures that sensitive or dynamic content is always up-to-date, striking a balance between performance optimization and data integrity.

Example nuxt.config.ts with routeRules

typescript

Copy

Enabling In-Application Caching

If you prefer to leverage the Storefront Application's built-in cache for rendered page responses, you can easily do so. Simply remove the headersOnly: true option from your route rules. This can be useful, for example, if you host the Storefront Application yourself and don't use a global CDN.

With in-application caching enabled, you can further refine its behavior by configuring the following cache options:

• group: 'ssr' and name: 'page' : These settings add ssr:page to the cache key prefix. This makes your Server-Side Rendered cache entries easy to identify and manage, improving clarity when inspecting your cache.
• varies: ['host', 'x-forwarded-host'] : This option appends the host and x-forwarded-host header values to your cache keys. This is particularly important if you're using domain-based routing, as it ensures that different domains retrieve the correct cached version.
• base: 'storefront-cache' : By default, Nuxt uses its built-in in-memory cache. By setting the base option to a custom name (e.g., 'storefront-cache'), the SSR cache will use the specific storage you have configured for that name within your application. This offers greater flexibility, allowing you to utilize various storage backends beyond just in-memory, such as Redis or other persistent stores.

Final In-Application Caching example

typescript

Copy

For an in-depth overview of the available routeRule configuration options per route, check the Nuxt - Route Rule documentation.

Use Cache in RPC Methods

The RpcContext object includes a cached function. It takes as its first argument a function to be executed, and cache options as its second argument. It returns a wrapped version of the passed-in function that caches the result of the function and will re-use the result on subsequent calls.

Available cache options for context.cached():

typescript

Copy

Example RpcContext Usage

typescript

Copy

Disable Cache

The Storefront SDK's internal cache, using context.cached(), and SSR cache can be enabled/disabled:

Internal cache

• At build-time: By setting the module configuration cache.enabled in nuxt.config.ts.
• At runtime: Via the NUXT_STOREFRONT_CACHE_ENABLED environment variable.

typescript

Copy

SSR Cache

• At runtime: Via the PAGE_CACHE_DISABLED environment variable.

Clear Cache

To prevent unauthorized cache clearing, you can optionally protect the API endpoints for cache management with basic authentication. This is configured by setting the cache.auth property within your module options in nuxt.config.ts, where you'll provide a username and password.

typescript

Copy

Once configured, all requests to the cache clearing endpoints will need to include an Authorization header with the base64 encoded credentials

The cache can be cleared by sending requests to specific API endpoints:

• Purge All: The /api/purge/all endpoint will clear the entire cache.
  sh

  Copy
• Purge by Tags: The /api/purge/tags endpoint will clear all cache keys for the specified tags.
  sh

  Copy

Test Caching with Vite

For testing purposes with Vite, it might be necessary to override the default storefront.storage configuration and set the driver to 'memory'.

Example Pseudo Test Case

typescript

Copy

References

• Nuxt Rendering Modes

Nitro

• Nitro - Storage Layer
• Nitro - Cache API
• Nitro - Plugin
• Nitro Route Rules
• Nitro caching layer