---
title: Quickstart
description: Install Cache Tags, point it at your frontend, and watch a publish purge exactly the pages that changed.
seo:
  image: /og/quickstart.png
---

1. **Install the package**

    ```sh
    dotnet add package TheBuilder.CacheTags --prerelease
    ```

    Start the site. The package creates its tables on the first start. From then on, every cacheable Delivery API response carries its keys in a header:

    ```http
    GET /umbraco/delivery/api/v2/content/item/articles/harbour-mornings/

    X-Umbraco-Cache-Keys: umbraco, content-e0000000-0000-0000-0000-000000000003
    ```

    Preview requests, signed-in requests and responses other than 200 get no keys.

2. **Tag your cache entries**

    Tag each cached response with the keys in its header. In Next.js with Cache Components:

    ```ts lib/umbraco.ts
    import { cacheLife, cacheTag } from "next/cache";

    export async function deliveryApi<T>(path: string): Promise<T | null> {
      "use cache";
      const url = `${process.env.UMBRACO_URL}/umbraco/delivery/api/v2/${path}`;
      const response = await fetch(url);
      if (!response.ok) {
        // An error carries no keys, so no purge would reach it. Keep it only briefly.
        cacheLife("seconds");
        return null;
      }
      cacheTag(...(response.headers.get("x-umbraco-cache-keys")?.split(", ") ?? []));
      cacheLife("days");
      return response.json();
    }
    ```

    The [Next.js guide](/nextjs) handles errors, cultures and an API key too.

3. **Add the purge webhook**

    Your frontend needs a route that receives purges and expires the keys in them. Copy the route handler from the [Next.js guide](/nextjs#the-purge-webhook). It checks the signature, then calls `revalidateTag` for each key.

4. **Point the package at it**

    In Umbraco, go to **Settings > Advanced > Cache tags > Targets** and select **Add target**. Enter the webhook's URL and a signing secret, then select **Send test purge** to check it before you save.

    A secret typed into the backoffice is stored in the database in plain text. Outside local development, set it as an environment variable such as `CacheTags__Secrets__WebhookSecret`, and have the target name `WebhookSecret` instead. See [Purge targets](/targets#in-the-backoffice).

    You can configure the target in `appsettings.json` instead:

    ```json appsettings.json
    {
      "CacheTags": {
        "Targets": {
          "nextjs": {
            "Url": "https://www.example.com/api/cache-tags",
            "Secret": "<at least 32 random characters>"
          }
        }
      }
    }
    ```

    Keep the secret out of source control. Set it as the environment variable `CacheTags__Targets__nextjs__Secret`, or in your host's secret store, and leave it out of the file.

    Give the frontend the same secret, as `CACHE_TAGS_WEBHOOK_SECRET`, and use a different one for each environment. To generate one:

    ```sh
    openssl rand -base64 32
    ```

5. **Publish something**

    Publish a page your frontend shows. Within a second or two, **Settings > Advanced > Cache tags > Changes** shows the change, the keys it planned and the purge it sent. The page, and every listing that shows it, renders the new content on its next request.

    The page's **Info** tab lists the cached responses that include it, and can purge it by hand. See [Backoffice](/backoffice).