The onCreation static method of the CacheHandler class is designed to facilitate the creation of a custom cache instance with configurable behavior. It accepts a single argument, onCreationHook, which is a function that returns a CacheHandlerConfig object.

onCreationHook

The onCreation method expects a function of type OnCreationHook, which is defined as follows:

type OnCreationHook = (context: CacheCreationContext) => Promise<CacheHandlerConfig> | CacheHandlerConfig;

Arguments

context

The context argument is an object of type CacheCreationContext, providing additional information for cache configuration. It includes the following properties:

1. serverDistDir (string):

   • Description: The absolute path to the Next.js server directory.
   • Purpose: This path is critical for locating server-side resources and files that may be required by the cache implementation, such as directories for storing cache data in the file system.

2. dev (boolean, optional):

   • Description: Indicates whether the Next.js application is running in development mode.
   • Purpose: This flag can be used to alter cache behavior based on the environment.

3. buildId (string, optional):

   • Description: A unique identifier for the current build of the Next.js application, generated during the next build process.
   • Purpose: The buildId may be used as a prefix for namespacing cache keys, ensuring distinct and relevant cache data for each build of the application.

Return Value

The CacheHandlerConfig type is designed to specify the list of cache Handlers and TTL policy.

Example

Here’s an example of how the onCreation method might be used:

CacheHandler.onCreation(async (context) => {
  const mainHandler = {
    // Define custom get, set, and other Handler methods
  };
 
  const fallbackHandler = {
    // Define custom get, set, and other Handler methods
  };
 
  return {
    handlers: [mainHandler, fallbackHandler],
    ttl: { defaultStaleAge: 3600, estimateExpireAge: (staleAge) => staleAge * 2 },
  };
});

In this example, the onCreation method configures two Handlers, and a common TTL policy for the cache.