Populating the Cache with the Initial Data

This feature is experimental. To use it, you must explicitly opt in by defining experimental.instrumentationHook = true; ↗ (opens in a new tab) in your next.config.js file.

Next.js pre-renders pages during the build process and stores them on the disk. This procedure bypasses the CacheHandler, so pre-rendered pages and routes are not added to the CacheHandler cache stores. To populate the cache with the initial data, you can utilize the registerInitialCache function from @neshca/cache-handler/instrumentation:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { registerInitialCache } = await import('@neshca/cache-handler/instrumentation');
    // Assuming that your CacheHandler configuration is in the root of the project and the instrumentation is in the src directory.
    // Please adjust the path accordingly.
    // CommonJS CacheHandler configuration is also supported.
    const CacheHandler = (await import('../cache-handler.mjs')).default;
 
    await registerInitialCache(CacheHandler, {
      // By default, it populates the cache with pre-rendered pages, routes, and fetch calls.
      // You can disable these features by setting the options to false.
      // For example, if you want to populate the cache with only pre-rendered pages, you can set the options as follows:
      fetch: false,
      routes: false,
    });
  }
}

This instrumentation will fill the cache with the initial data when the application starts. The duration of this process may vary based on the number and size of pages, routes, and fetch calls.

Using output: 'standalone' in next.config.js

If you use the output: 'standalone' option in your next.config.js file, you must copy the fetch-cache directory to the standalone directory. Otherwise, the instrumentation will not pre-populate the cache with the initial fetch calls data.

To copy the fetch-cache directory, run the following command in your project root directory:

mkdir -p .next/standalone/.next/cache/fetch-cache
cp .next/cache/fetch-cache/* .next/standalone/.next/cache/fetch-cache/

Or using Dockerfile:

COPY .next/cache/fetch-cache/ .next/standalone/.next/cache/fetch-cache/

Caveats

When using the output: 'standalone' option in a monorepo, you may need to adjust the paths in the above command to match your project structure.

For example, they may look like this:

mkdir -p .next/standalone/<path-to-your-app-in-the-monorepo>/.next/cache/fetch-cache
cp .next/cache/fetch-cache/* .next/standalone/<path-to-your-app-in-the-monorepo>/.next/cache/fetch-cache/

You may also need to configure outputFileTracingRoot in your next.config.js to work locally. Refer to the Next.js output: standalone option ↗ (opens in a new tab) for more information.

Usful links

• Instrumentation Next.js documentation ↗ (opens in a new tab)
• Next.js output: standalone option ↗ (opens in a new tab)