Purge CDN Cache

With Smart CDN enabled, Supabase Storage automatically invalidates the cache when files are updated or deleted. However, there are scenarios where you may need to manually purge the CDN cache for specific objects or entire buckets. The cache purge API allows you to immediately queue cache content invalidation across all CDN edge nodes.

Manual cache purging is useful when you need to ensure that updates are propagated as soon as possible, or when you want to clear the cache for debugging purposes. Once purged, the next request for that object will be served from the origin server, and the CDN cache will be repopulated.

Purge a single object#

You can purge the CDN cache for a specific file by providing the exact path to the object. This operation does not support wildcards or recursion. You must specify the complete path of the file you want to invalidate.

1
import { createClient } from '@supabase/supabase-js'
2
3
// Create Supabase client with secret key
4
const supabase = createClient('your_project_url', 'your_secret_key')
5
6
// Purge cache for a single object
7
async function purgeCachedObject() {
8
  const { data, error } = await supabase.storage
9
    .from('bucket_name')
10
    .purgeCache('folder_name/file_name.png')
11
12
  if (error) {
13
    // Handle error
14
  } else {
15
    // Handle success
16
    console.log(data.message) // 'success'
17
  }
18
}

Purge an entire bucket#

For scenarios where you need to invalidate all cached objects in a bucket, you can purge the entire bucket's cache. This is useful when performing bulk updates or major changes to your storage bucket.

1
import { createClient } from '@supabase/supabase-js'
2
3
// Create Supabase client with secret key
4
const supabase = createClient('your_project_url', 'your_secret_key')
5
6
// Purge cache for an entire bucket
7
async function purgeBucketCache() {
8
  const { data, error } = await supabase.storage.purgeBucketCache('bucket_name')
9
10
  if (error) {
11
    // Handle error
12
  } else {
13
    // Handle success
14
    console.log(data.message) // 'success'
15
  }
16
}

Cache propagation#

After purging the cache, it can take up to 60 seconds for the invalidation to propagate across all CDN edge nodes worldwide. During this time, some users may still receive cached content depending on which edge node they are routed to.

Keep in mind that purging the CDN cache does not affect browser caches. If users have the asset cached locally in their browser, they will continue to see the cached version until the browser cache expires based on the cacheControl value set during upload.