👉 Visit the DatoCMS homepage or see What is DatoCMS?

---

Next.js + DatoCMS Cache Tags

Everything you need to know to build a Next.js project powered by DatoCMS Cache Tags to achieve the perfect balance of performance, efficiency, and real-time updates.

Table of Contents

• Table of Contents
• Getting Started
  • Step 1: Clone the DatoCMS project
  • Step 2: Environment variables
    • PUBLIC_DATOCMS_API_TOKEN
    • WEBHOOK_TOKEN
    • TURSO_DATABASE_URL, TURSO_AUTH_TOKEN
  • Step 3: Install dependencies and download the DatoCMS GraphQL Schema
  • Step 4: Run development server
• Deployment
• Useful resources to navigate the code
  • Execution of GraphQL queries
  • "Cache Tags Invalidation" webhook

Getting Started

Step 1: Clone the DatoCMS project

Start by pressing this button to create a new project on DatoCMS containing the data expected by this project:

Step 2: Environment variables

Use .env.local.example file as a starting point:

cp .env.local.example .env.local

Now open .env.local and start populating the variables:

PUBLIC_DATOCMS_API_TOKEN

The "GraphQL API Token" from the DatoCMS project you just created. Learn to find/create an API token.

WEBHOOK_TOKEN

Any secure random string. It will be used to authenticate the webhook requests that come from DatoCMS.

TURSO_DATABASE_URL, TURSO_AUTH_TOKEN

Simply click the following button to create and initialize a Turso database with the expected schema (sign up or log in to Turso is required):

Copy the database URL and use it to fill the TURSO_DATABASE_URL environment variable.

Also create a token for the database, with no expiration and read/write permissions: copy and use it for the TURSO_AUTH_TOKEN variable.

We selected Turso because it's an incredibly cost-effective solution and is compatible with any hosting service. However, any other storage solution would be just as effective due to the simplicity of the saved data.

Step 3: Install dependencies and download the DatoCMS GraphQL Schema

Simply run npm install (or the equivalent command for your package manager of choice): a schema.graphql will be generated.

Step 4: Run development server

Now you can run the development server:

npm run dev

Open http://localhost:3000 with your browser to see the result.

Deployment

The project runs smoothly on both Vercel and Netlify. Just ensure to set the environment variables as previously explained. For your convenience, you can deploy the project on Vercel using this button:

Important: Once the site is deployed and you know the final domain, you need to set up a "Invalidate cache tag" webhook on your DatoCMS project, configured like this:

• URL: https://<YOUR-DOMAIN>/api/invalidate-cache-tags
• Custom headers: Webhook-Token: <YOUR_WEBHOOK_TOKEN>
• Trigger:
  • Entity: Content Delivery API Cache Tags
  • Events: Invalidate

Useful resources to navigate the code

This repository aims to demonstrate how you can selectively invalidate the Next.js cache when receiving DatoCMS Cache Tags invalidation events. Before exploring this repository, it's very useful to understand the general concepts behind Cache Tags:

• DatoCMS Cache Tags: Announcement, Documentation
• Cache Tags with Next.js: Guide

The code essentially consists of two parts that are strongly interdependent:

Execution of GraphQL queries

The executeQuery() function is responsible for executing a GraphQL query using the DatoCMS Content Delivery API and caching the result. To support cache invalidation, the request is tagged with a unique identifier in the Next.js Data Cache.

The mapping between the unique identifier of the query, and the DatoCMS Cache Tags returned in the response is stored in Turso. We use a simple table made up of just two columns:

• query_id (TEXT): A unique identifier for the query, used to tag the request;
• cache_tag (TEXT): The actual cache tag returned by the query.

You can switch the storage option from Turso to other options by adjusting the code in lib/database.ts.

"Cache Tags Invalidation" webhook

The route handler /api/invalidate-cache-tags receives "Cache Tag Invalidation" events from a DatoCMS webhook and is responsible for invalidating every cached GraphQL query that is linked to those tags.

Since the executeQuery():

• Tags each GraphQL request with a unique ID in the Next.js Data Cache, and
• Saves the "Query ID <-> Cache Tags" mapping on a Turso database...

The endpoint can find in the database the query IDs associated with the received tags, and use revalidateTag() to invalidate the relevant requests.

---

What is DatoCMS?

DatoCMS is the REST & GraphQL Headless CMS for the modern web.

Trusted by over 25,000 enterprise businesses, agency partners, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our developers, content editors and marketers!

Quick links:

• ⚡️ Get started with a free DatoCMS account
• 🔖 Go through the docs
• ⚙️ Get support from us and the community
• 🆕 Stay up to date on new features and fixes on the changelog

Our featured repos:

• datocms/react-datocms: React helper components for images, Structured Text rendering, and more
• datocms/js-rest-api-clients: Node and browser JavaScript clients for updating and administering your content. For frontend fetches, we recommend using our GraphQL Content Delivery API instead.
• datocms/cli: Command-line interface that includes our Contentful importer and Wordpress importer
• datocms/plugins: Example plugins we've made that extend the editor/admin dashboard
• DatoCMS Starters has examples for various Javascript frontend frameworks

Or see all our public repos