Purging Vercel CDN Cache

Learn how to invalidate and purge cached content on Vercel's CDN, including cache keys and manual purging options.

Each request to Vercel's CDN has a cache key derived from the following:

• The request method (such as GET, POST, etc)
• The request URL (query strings are ignored for static files)
• The host domain
• The unique deployment URL
• The scheme (whether it's https or http)

Since each deployment has a different cache key, you can promote a new deployment to production without affecting the cache of the previous deployment.

When you invalidate a cache tag, all cached content associated with that tag is marked as stale. The next request serves the stale content instantly while revalidation happens in the background. This approach has no latency impact for users while ensuring content gets updated.

When you delete a cache tag, the cached entries are marked for deletion. The next request fetches content from your origin before responding to the user. This can slow down the first request after deletion. If many users request the same deleted content simultaneously, it can create a cache stampede where multiple requests hit your origin at once.

Cache tags are user-defined strings that can be assigned to cached responses. These tags can later be used to purge the the CDN cache.

For example, you may have a product with id 123 that is displayed on multiple pages such as /products/123/overview, /products/123/reviews, etc. If you add a unique cache tag to those pages, such as product123, you can invalidate that tag when the content of the product changes.

You can add a cache tag by importing addCacheTag from the @vercel/functions npm package and passing your tag.

If you're using Next.js, you can import cacheTag from 'next/cache' instead.

Cache tags are case-sensitive, meaning product and Product are treated as different tags.

Cache tags are scoped to your project and environment (production or preview).

When you purge a tag with the REST API, you can optionally provide a target environment such as preview or production (default is all environments).

When you purge a tag using @vercel/functions at runtime, the function's current environment is used which is derived from the deployment url that invoked the function.

You can purge Vercel CDN cache in any of the following ways:

• next/cache: Use helper methods like revalidatePath(), revalidateTag(), or updateTag()
• @vercel/functions: Use helper methods like invalidateByTag(), dangerouslyDeleteByTag(), invalidateBySrcImage(), or dangerouslyDeleteBySrcImage()
• Vercel CLI: Use the vercel cache invalidate command or vercel cache dangerously-delete command with --tag or --srcimg options
• REST API: Make direct API calls to the edge cache endpoint like /invalidate-by-tag, /dangerously-delete-by-tag, /invalidate-by-source-image, or /dangerously-delete-by-source-image

In some circumstances, you may need to delete all cached data and force revalidation. For example, you might have set a Cache-Control to cache the response for a month but the content changes more frequently than once a month. You can do this by purging the cache:

1. Under your project, go to the Settings tab.
2. In the left sidebar, select Caches.
3. In the CDN Cache section, click Purge CDN Cache.
4. In the dialog, you'll see two options:
   • Invalidate: Marks a cache tag as stale, causing cache entries associated with that tag to be revalidated in the background on the next request. This is the recommended method for most use cases.
   • Delete: Marks a cache tag as deleted, causing cache entries associated with that tag to be revalidated in the foreground on the next request. Use this method with caution because one tag can be associated with many paths and deleting the cache can cause many concurrent requests to the origin leading to cache stampede problem. This option is for advanced use cases and is not recommended; prefer using Invalidate instead.
5. In the dialog, you'll see a dropdown with two options:
   • Cache Tag: Purge cached responses associated with a specific user-defined tag.
   • Source Image: Purge Image Optimization transformed images based on the original source image URL.
6. In the dialog, enter a tag or source image in the input. You can use * to purge the entire project.
7. Finally, click the Purge button in the dialog to confirm.

The purge event itself is not billed but it can temporarily increase Function Duration, Functions Invocations, Edge Function Executions, Fast Origin Transfer, Image Optimization Transformations, Image Optimization Cache Writes, and ISR Writes.