docs: updates to on-demand validation quick start

Author: backlineint

www/content/tutorials/on-demand-revalidation/configure-entity-types.mdx

@@ -15,11 +15,22 @@ A _revalidator_ tells Drupal how to revalidate an entity when it is created, upd
 
 </Callout>
 
+### Configure Tag-based Revalidation
+
 1. Visit `/admin/config/services/next/entity-types`
 2. Click **Configure entity type** or **Edit** an existing one
 3. Click **On-demand Revalidation**
-4. Select **Path** as the revalidator **Plugin**
-5. Check **Revalidate page**
+4. Select **Cache Tag** as the revalidator **Plugin**
+5. If using the **Path** plugin, check the **Revalidate page** checkbox
 6. Click **Save**
 
+### Configure Path-based Revalidation
+
+7. Visit `/admin/config/services/next/entity-types`
+8. Click **Configure entity type** or **Edit** an existing one
+9. Click **On-demand Revalidation**
+10. Select **Path** as the revalidator **Plugin**
+11. Check the **Revalidate page** checkbox
+12. Click **Save**
+
 If you want to revalidate multiple pages, you can configure **Additional paths**. Example: you might want to revalidate the `/blog` landing page when an Article is created.

www/content/tutorials/on-demand-revalidation/configure-revalidate-route.mdx

@@ -7,35 +7,50 @@ group: On-demand Revalidation
 
 Implement on-demand revalidation using an API route at `/revalidate`.
 
+## Update Environment Variables
+
+First, update `.env.local` to include the revalidate secret you specified.
+
+```txt title=.env.local
+# Required for On-demand Revalidation
+DRUPAL_REVALIDATE_SECRET=secret
+```
+
+## Create the Revalidate Route
+
+Next, create the API route that will be used for on-demand revalidation.
+
 <Callout>
 
-If you're using the Basic Starter, revalidate route are already created for you. You can skip this step.
+If you're using the Basic Starter, the revalidate route is already created for you. You can skip this step.
 
 </Callout>
 
 ## /app/api/revalidate/route.ts
 
 ```ts title=app/api/revalidate/route.ts
-import { revalidatePath } from "next/cache"
+import { revalidatePath, revalidateTag } from "next/cache"
 import type { NextRequest } from "next/server"
 
 async function handler(request: NextRequest) {
   const searchParams = request.nextUrl.searchParams
   const path = searchParams.get("path")
+  const tags = searchParams.get("tags")
   const secret = searchParams.get("secret")
 
   // Validate secret.
   if (secret !== process.env.DRUPAL_REVALIDATE_SECRET) {
     return new Response("Invalid secret.", { status: 401 })
   }
 
-  // Validate path.
-  if (!path) {
-    return new Response("Invalid path.", { status: 400 })
+  // Either tags or path must be provided.
+  if (!path && !tags) {
+    return new Response("Missing path or tags.", { status: 400 })
   }
 
   try {
-    revalidatePath(path)
+    path && revalidatePath(path)
+    tags?.split(",").forEach((tag) => revalidateTag(tag))
 
     return new Response("Revalidated.")
   } catch (error) {

www/content/tutorials/on-demand-revalidation/index.mdx

@@ -7,8 +7,4 @@ group: On-demand Revalidation
 
 [On-demand Revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation) makes it easy to update your Next.js site when content on Drupal is created, updated or deleted.
 
-Starting with `v1.6.0`, Next.js for Drupal supports On-demand Revalidation configurable per entity types.
-
-TODO - in v2, Next.js for Drupal supports...
-TODO - maybe this section should just be renamed to validation?
-TODO - maybe move revalidation examples from Building Pages to this section...
+Next.js for Drupal supports On-demand Revalidation configurable per entity types. You can choose to revalidate content by path, or by tag. Tag-based invalidation is new as of Next Drupal 2.0 and allows you to invalidate content on your Next.js site using Drupal's powerful cache tag system.

www/content/tutorials/on-demand-revalidation/set-revalidation-parameters.mdx

@@ -0,0 +1,89 @@
+---
+title: Set Revalidation Parameters
+excerpt: Set Revalidation Parameters When Fetching Data in Next.js
+weight: 370
+group: On-demand Revalidation
+---
+
+When fetching data using the Next Drupal Client, you will also need to set the necessary revalidation parameters. This tells Next.js that the content should be cached, and what metadata can be used to invalidate that cache.
+
+<Callout>
+
+If you're using the Basic Starter, most of this configuration is already created for you. You will only need to replace `revalidate` with `tags` in the options object when using Next Drupal Client methods like `getResource` if you'd prefer to use tag-based revalidation.
+
+</Callout>
+
+Consider the `getNode` function in the `[...slug]` dynamic route in the basic starter:
+
+```ts title=app/[..slug]/page.tsx
+async function getNode(slug: string[]) {
+  const path = `/${slug.join("/")}`
+
+  const params: JsonApiParams = {}
+
+  // Translating the path also allows us to discover the entity type.
+  const translatedPath = await drupal.translatePath(path)
+
+  if (!translatedPath) {
+    throw new Error("Resource not found", { cause: "NotFound" })
+  }
+
+  const type = translatedPath.jsonapi?.resourceName!
+  const uuid = translatedPath.entity.uuid
+  const tag = `${translatedPath.entity.type}:${translatedPath.entity.id}`
+
+  if (type === "node--article") {
+    params.include = "field_image,uid"
+  }
+
+  const resource = await drupal.getResource<DrupalNode>(type, uuid, {
+    params,
+    cache: "force-cache",
+    next: {
+      revalidate: 3600,
+      // Replace `revalidate` with `tags` if using tag based revalidation.
+      // tags: [tag],
+    },
+  })
+
+  return resource
+}
+```
+
+## Path-based Revalidation
+
+The call to `getResource` in the above example is already configured to use path-based invalidation. The data will be cached for 3600 seconds unless revalidated on-demand.
+
+```tsx
+const resource = await drupal.getResource<DrupalNode>(type, uuid, {
+  params,
+  cache: "force-cache",
+  next: {
+    revalidate: 3600,
+  },
+})
+```
+
+## Tag-based Revalidation
+
+To instead use tag-based invalidation, we can replace the `revalidate` option with the `tags` option:
+
+```tsx
+const resource = await drupal.getResource<DrupalNode>(type, uuid, {
+  params,
+  cache: "force-cache",
+  next: {
+    tags: [tag],
+  },
+})
+```
+
+In this example, the tag is set earlier in the function using data from the translated path:
+
+```tsx
+const type = translatedPath.jsonapi?.resourceName!
+const uuid = translatedPath.entity.uuid
+const tag = `${translatedPath.entity.type}:${translatedPath.entity.id}`
+```
+
+This option accepts an array of tags, and values should match the cache tag values set by Drupal. With this configuration, the data will be cached until Drupal makes a call to the revalidate route using any of the matching cache tags.