Skip to main content

Caching Recommendations

Learn about caching recommendations for your Drupal frontend starter kit.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

Warning

This documentation is considered deprecated. If you use Front-End Sites today, we encourage you to migrate.

Cache settings are configured out-of-the-box for you, but there are circumstances in which you might need to make your own configurations, such as when your CMS is not on Pantheon but your frontend is on Pantheon.

How it Works

Edge caching can improve performance for Front-End Sites that rely on API endpoints, and also reduce the load on your CMS in cases when a large number of API requests are made in a short period of time, such as during a full site build process.

Surrogate keys enable more flexible purging because cached responses include metadata. Surrogate keys allow you to tag responses with specific identifiers. For example, you can use the Surrogate-Key header to tag content with a key term. You can then selectively purge requests tagged with the key term.

Your CDN is forced to request a new version of your content when you purge cached content. This ensures that visitors to your site see your latest content changes.

Using the Starter Kit

Note

The Front-End Sites starter kits use Next.js 13 and the Pages Router. The instructions below only apply to the Pages Router and are not currently compatible with the App Router.

The recommended caching configurations are automatically enabled if you created your Drupal site using the Drupal + Next.js frontend starter project.

The PantheonDrupalState class from the @pantheon-systems/drupal-kit npm package includes an adapted fetch method that adds the Pantheon-SKey header to each request sent to Drupal. Responses from Drupal contain the Surrogate-Key header. You can use these keys to instruct your frontend to purge content from a cache when the content in Drupal changes.

Cache Control Headers

This section explains how to set Cache-Control headers using @pantheon-systems/drupal-kit in the next-drupal-starter, or any Next.js application using the drupal-kit. Our @pantheon-systems/drupal-kit exports DrupalState, a class that includes a local store and helper methods to fetch data from Drupal. Included in these methods is a default Cache-Control header that is set on the response object that is passed into the DrupalState helper.

The default Cache-Control header value is as follows:

Override Drupal Kit's Default Cache-Control Headers

The @pantheon-systems/drupal-kit's Drupal State store sets the default header when you pass in the response object to any of the data fetching methods like getObject and getObjectByPath.

To override this default with your own Cache-Control header value, use the Next.js res.setHeader method as shown in the example:

You can take advantage of this feature without using the starter kit.

Purge Edge Caching

Ensure Headers Are Set for Custom Routes

Note

The Decoupled Kit Drupal Backend Starter Project and Drupal Next.js Starter Kit handle the configuration below automatically. You do not need to make configuration changes for existing routes because the starter kit configures this for you.

  1. Make sure the Drupal backend has the Pantheon Advanced Page Cache module installed and configured.

  2. Create an instance of PantheonDrupalState imported from @pantheon-systems/drupal-kit in your application.

  3. Use the fetch methods available (refer to drupal-kit for more information). The Surrogate-Key header should be set automatically if Drupal is configured correctly.

  4. Pass the context.res from getServerSideProps into the PantheonDrupalState fetch method so that the headers are added to the outgoing response.

Create a New Route

Follow the steps below if you need to create a new route.

In the example below, the code sets the headers necessary for cache purging on an article list page.

  1. Create an instance of DrupalState in your article list page:

  2. Use the store instance in getSeverSideProps to fetch data from Drupal and provide the outgoing response object:

    • You should now see the Surrogate-Key header on the outgoing response for /articles/ if your backend is configured correctly. This allows the cache for this page to be purged automatically when any related content changes in Drupal.

More Resources