How the Filestack CDN Delivers Your Files Fast Across the Globe

When a user in Tokyo opens your app and waits for an image hosted in Virginia, every millisecond shows. That’s where a content delivery network steps in. The Filestack CDN sits between your storage and your users, serving files from the location nearest to them.

In this guide, we’ll walk through how the CDN works, how to control caching behavior, and how to serve responsive images that adapt to each device. By the end, you’ll know how to deliver assets globally with predictable performance.

Key Takeaways

• Every Filestack file is delivered through the CDN by default. Append a file handle to https://cdn.filestackcontent.com/ and you have a public URL.
• Cached files live for 30 days. That window resets each time the file is requested again.
• Use cache=false for testing only. Production traffic should rely on the cache to save quota and reduce latency.
• Custom expiry times let you fine-tune cache behavior. Pass cache=expiry:VALUE in seconds.
• The adaptive library generates responsive <picture> elements. Smaller files for smaller screens, with automatic WebP support.

What the Filestack CDN Does

The CDN is the delivery layer for every file managed by your Filestack application. As soon as a file is uploaded or transformed, it becomes accessible through a single base URL:

https://cdn.filestackcontent.com/HANDLE

The HANDLE is the unique identifier returned when a file is uploaded through the File API or the File Picker. From that point on, anyone with the URL can access the file, and the CDN routes the request to the nearest edge node.

This matters because edge delivery cuts round-trip time. A user in Berlin gets the asset from a European edge, while a user in São Paulo gets it from a South American edge. Same URL, different physical paths.

How Caching Works

The Filestack CDN caches a URL the first time it is requested. This applies to standard file handles, storage aliases, and any URL with transformation tasks applied.

Each cached copy lives for 30 days. After that, the file gets re-cached on the next request. As a result, frequently accessed assets stay hot in cache, while rarely used ones drop out and reload on demand.

Bypassing the Cache

Sometimes you want a fresh copy directly from the storage backend. For example, when you’re testing a newly uploaded version of a file. To skip the cache, add the /cache=false/ task to your URL:

https://cdn.filestackcontent.com/cache=false/HANDLE

Use this sparingly. Every cache=false request bypasses the optimization layer, so it costs more in latency and counts against your transformation quota.

Setting a Custom Expiry

If you want explicit control over how long a file stays cached, pass the cache=expiry:VALUE task with the value in seconds:

https://cdn.filestackcontent.com/cache=expiry:3600/HANDLE

The example above keeps the file cached for one hour. For full reference details on the /cache/ task, see the Processing API documentation.

A few important notes on how caching is determined:

• Files are cached by unique URL. That means https://cdn.filestackcontent.com/HANDLE and https://cdn.filestackcontent.com/resize=width:300/HANDLE are two separate cache entries.
• Security policies and signatures are excluded from URL uniqueness. Two requests for the same file with different signed policies share the same cache entry.
• Infrequent access can trigger purging. If a file is rarely requested, the CDN may purge it before its expiry, regardless of the value you set.

Serving Responsive Images

Modern web apps deal with screens ranging from small phones to large desktop displays. Delivering the same image to all of them wastes bandwidth on smaller devices and stretches pixels on larger ones.

The Filestack adaptive library solves this by generating HTML <picture> elements powered by the CDN. The <picture> element is a standard part of the HTML specification, and it lets the browser pick the right image based on viewport size and your defined breakpoints. For background on the element itself, the MDN documentation on <picture> is a solid reference.

Here’s a basic example of what adaptive generates:

<picture>

  <source media="(max-width: 600px)"

          srcset="https://cdn.filestackcontent.com/resize=width:600/HANDLE">

  <source media="(max-width: 1200px)"

          srcset="https://cdn.filestackcontent.com/resize=width:1200/HANDLE">

  <img src="https://cdn.filestackcontent.com/HANDLE" alt="Responsive asset">

</picture>

The browser checks the viewport, picks the matching source, and downloads only that variant. Smaller screens get smaller files, which means faster page loads and lower mobile data usage.

Adaptive also handles WebP delivery automatically. When the browser supports WebP, the library requests the WebP variant; otherwise, it falls back to the original format. Combined with the CDN’s edge caching, this delivers the right image format, at the right size, from the right location.

Putting It All Together

Once you understand these three pieces, the CDN, the cache controls, and the adaptive library, you can build a delivery strategy that fits your application:

• For static marketing assets, use the default cache behavior. Files stay cached for 30 days, and edge delivery handles the rest.
• For user-generated content, combine transformations with the standard cache. The first request triggers processing, and every subsequent request hits the edge.
• For time-sensitive content like dashboard exports, pass cache=expiry: with a short value so updates propagate quickly.
• For media-heavy pages, integrate the adaptive library to serve right-sized images per device.

What’s Next

Now that you have a working model of how the CDN delivers files, you can dig deeper into related areas:

• Custom CNAME for serving assets on your own domain
• Storage Aliases for routing to multiple backends
• Processing API for the full set of transformation tasks
• Security Policies for signed URLs and access control

Ready to start delivering files at scale? Get your free API key and start serving assets through the Filestack CDN today.

Read More →