Manage cache tags for external origins

This guide shows you how content served from an external origin through Vercel’s CDN can be cached and selectively invalidated so it is only regenerated when data changes.

Copy link to headingWhy use Vercel's CDN for external origins

Vercel's CDN improves performance and security when proxying requests to external origins, or origins that are hosted somewhere other than Vercel. The CDN reduces latency by caching content close to the user in all Vercel Regions worldwide, while the Vercel Firewall protects against threats like DDoS attacks, bot traffic, and malicious requests before they reach your servers.

Copy link to headingThe problem

Users want to see content delivered very quickly from anywhere in the world. Caching improves performance by storing and serving the content close to users, but the content also needs to be fresh and updated as soon as data changes. When data changes, you have two options for how to make sure the content is fresh:

1. Purge all cached content - This option is too coarse and hurts performance and costs for unchanged content. Users have to make a request back to the origin on the next request which will be slow.
2. Purge specific content - This option requires assigning tags to specific pages that are updated at the same time. Content can be invalidated so that a stale page is served to the user on the next request while the cache is refreshed in the background.

Cache tags solve this by letting you organize cached responses into groups that you can invalidate at the same time. Other requests that are tagged differently are unaffected. Cache tags may also be referred to as surrogate keys on other platforms.

The rest of this guide will walk you through how to use and invalidate cache tags in your application.

Copy link to headingPrerequisites

• A Vercel project with rewrites to an external origin
• An external origin that can set response headers
• The Vercel CLI installed

Copy link to headingCaching rewrites to an external origin on Vercel

A rewrite routes a request to a different destination without changing the URL in the browser. Unlike redirects, the user won't see the URL change.

To set up a rewrite, configure the vercel.json with the following code:

{
  "rewrites": [
    {
      "source": "/api/(.*)",
      "destination": "https://api.yourdomain.com/api/$1"
    }
  ]
}

The flow for a request will be:

1. User requests yourdomain.com/api/products/123
2. Vercel CDN checks for cached content
3. If not cached, Vercel fetches from api.yourdomain.com/api/products/123
4. Your server responds with content and cache tags
5. Vercel caches the response with those tags

Copy link to headingStep 1: Set cache tags from your external server

Configure your server to set the Vercel-Cache-Tag header:

1
app.get('/api/products/:id', async (req, res) => {
2
  const product = await getProduct(req.params.id);
3
  
4
  const tags = [
5
    `product-${req.params.id}`,
6
    `category-${product.category}`,
7
    'products'
8
  ];
9
  
10
  if (product.featured) {
11
    tags.push('homepage');
12
  }
13

14
  res.setHeader('Vercel-Cache-Tag', tags.join(','));
15
  res.setHeader('Cache-Control', 's-maxage=3600, max-age=60, stale-while-revalidate=86400');
16

17
  res.json(product);
18
});

What each tag does:

• product-123 - Invalidate when this specific product changes
• category-electronics - Invalidate when any product in this category changes
• products - Invalidate when the product catalog changes

Copy link to headingStep 2: Install and configure Vercel CLI

npm install -g vercel
vercel login

If you have multiple teams, make sure that you have selected the right team:

vercel teams switch your-team-name

Copy link to headingStep 3: Invalidate cache tags

Now that the Vercel CDN is caching content, you can selectively invalidate specific cache tags to see new content being picked up. When cache tags are invalidated, the next request will return the stale content while the Vercel CDN is refreshing the cache contents in the background. This maintains performance while making sure that subsequent requests get the fresh content.

There are different ways that content can be invalidated on Vercel

Copy link to headingInvalidate cache tags in code

Cache tags can be invalidated directly in code if you have a function or webhook that runs when data changes.

Option 1: Direct invalidation in your update function

The invalidateByTags function can be called from server side code in the same project that the tag is defined in.

1
import { Vercel } from "@vercel/sdk";
2

3
const vercel = new Vercel({
4
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
5
});
6

7
async function updateProduct(id, data) {
8
  await database.products.update(id, data);
9
  
10
  const tags = [
11
    `product-${id}`,
12
    `category-${data.category}`,
13
    'products'
14
  ];
15

16
  if (data.featured) {
17
    tags.push('homepage');
18
  }
19
  
20
  await vercel.edgeCache.invalidateByTags({
21
    projectIdOrName: "<value>",
22
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
23
    slug: "my-team-url-slug",
24
    requestBody: { tags },
25
  });
26
  
27
  return { success: true, invalidated: tags };
28
}

Option 2: CMS webhook handler

If data is updated in an external CMS, you can create a webhook route handler to receive the event when data changes and choose which tags to invalidate.

1
import { Vercel } from "@vercel/sdk";
2

3
const vercel = new Vercel({
4
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
5
});
6

7
export default async function handler(req, res) {
8
  if (req.method !== 'POST') {
9
    return res.status(405).json({ error: 'Method not allowed' });
10
  }
11
  
12
  const { event_type, resource_id, resource_type, data } = req.body;
13
  
14
  let tags = [];
15
  
16
  if (resource_type === 'product') {
17
    tags = [
18
      `product-${resource_id}`,
19
      `category-${data.category}`,
20
      'products'
21
    ];
22
    if (data.featured) tags.push('homepage');
23
  } else if (resource_type === 'category') {
24
    tags = [`category-${resource_id}`, 'categories'];
25
  }
26
  
27
  if (tags.length === 0) {
28
    return res.status(400).json({ error: 'No tags to invalidate' });
29
  }
30
  
31
  try {
32
    await vercel.edgeCache.invalidateByTags({
33
      projectIdOrName: "<value>",
34
      teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
35
      slug: "my-team-url-slug",
36
      requestBody: { tags },
37
    });
38
    res.json({ success: true, invalidated: tags });
39
  } catch (error) {
40
    res.status(500).json({ error: 'Cache invalidation failed' });
41
  }
42
}

Copy link to headingInvalidate via Vercel CLI

The Vercel CLI can also be used to invalidate at any time.

# Single tag
vercel cache invalidate --tag product-123

# Multiple tags (comma-separated)
vercel cache invalidate --tag "product-123,homepage,electronics"

Purge all cache:

Invalidate is the recommended option, but the Vercel CLI can also purge all cache content. This option isn’t recommended since it causes a blocking request to the external origin, but it can be used when all content must be updated.

# Purge all CDN cache
vercel cache purge --type cdn

# Purge all cache types
vercel cache purge

Copy link to headingSet cache tags via routing rules

If you are not able to set cache tags in the response from your external origin, you can still set cache tags on Vercel using routing rules.

Setting cache tags in vercel.json

{
  "routes": [
    {
      "source": "/products/electronics/(.*)",
      "destination": "https://api.example.com/api/products/$1",
      "headers": {
        "Vercel-Cache-Tag": "product-$1,category-electronics"
      }
    }
  ]
}

Setting cache tags from the CLI

Routing rules to set cache tags can also be set using the CLI to add routing rules without requiring you to change any code. Use the vercel routes CLI command:

# Add cache tags for the category and product ID when rewriting the request to the external origin
vc routes add "Electronics" --src "/products/electronics/:id" --src-syntax path-to-regexp --action rewrite --dest "https://api.example.com/api/products/:id" --set-response-header 'Vercel-Cache-Tag=product-$1,category-electronics'

Copy link to headingNext steps

Cache tags can be incrementally added to your application and optimized based on usage patterns and how often data is updated. Learn more about caching in the Vercel CDN Cache documentation.