Caching on Tilda

Tilda provides powerful caching capabilities through a two-layer caching architecture:

• CoreCache - A regional cache located in the same datacenter as your application, providing fast access to cached content. Framework features like Next.js ISR (Incremental Static Regeneration) and Next.js fetch cache use CoreCache to store and serve data.
• CDN Cache - A globally distributed cache network that serves content from points of presence (PoPs) closest to your end users

This multi-layer approach ensures optimal performance:

• CoreCache is currently accessible through Next.js ISR functions, providing fast regional caching for dynamic content. Support for other frameworks is coming soon.
• CDN cache can be controlled using HTTP response headers (Cache-Control, Tilda-Cache-Control, and Tilda-Cache-Tags), ensuring low-latency content delivery to users worldwide.

Cache Control Headers

Tilda supports the following headers for controlling CDN cache behavior:

• Cache-Control - Standard HTTP cache control header
• Tilda-Cache-Control - Tilda-specific cache control header
• Tilda-Cache-Tags - Tag-based cache invalidation header

Header Precedence

When both Cache-Control and Tilda-Cache-Control headers are present, Tilda-Cache-Control takes precedence for CDN caching directives. This allows you to set different caching behaviors for browsers and the CDN.

Cache Control Directives

Both Cache-Control and Tilda-Cache-Control support the following directives:

• max-age=[seconds] - How long to cache the content
• private - Content should not be cached by the CDN
• no-store - Content should never be cached
• stale-while-revalidate=[seconds] - Serve stale content while fetching fresh content
• stale-if-error=[seconds] - Serve stale content if origin errors occur

Example Usage

// Standard cache control
Cache-Control: max-age=3600

// Tilda-specific cache control
Tilda-Cache-Control: max-age=86400

// The above configuration will:
// - Cache in browsers for 1 hour
// - Cache in Tilda's CDN for 24 hours

Cache Tags

The Tilda-Cache-Tags header allows you to associate tags with cached content for selective cache invalidation. Tags must be comma-separated strings.

Example Usage

// Tag a product page
Tilda-Cache-Tags: products, product-123

// Tag a category page
Tilda-Cache-Tags: products, category-456, product-123, product-789, product-1011

Best Practices

Cache Duration

Consider these guidelines when setting cache durations:

• Static assets (images, CSS, JS): Long cache times (1 week or more)
• API responses: Shorter cache times based on data freshness needs
• Dynamic content: Use cache tags for precise invalidation

Stale Content

Use stale-while-revalidate and stale-if-error to improve reliability and performance:

// Serve stale content for up to 1 hour while fetching fresh content
Tilda-Cache-Control: max-age=3600, stale-while-revalidate=3600

// Serve stale content for up to 24 hours if origin is down
Tilda-Cache-Control: max-age=3600, stale-if-error=86400

Cache Keys

By default, Tilda generates cache keys using the full request URL, including:

• Protocol (http/https)
• Hostname
• Path
• Query parameters

Cache Status

Tilda adds an X-Cache response header to indicate cache status:

• HIT - Served from cache
• MISS - Not in cache, fetched from origin
• STALE - Served stale content
• BYPASS - Cache was bypassed

Cache Purging

You can purge cached content in three ways:

• Wait for the cache to expire naturally based on TTL
• Use Tilda dashboard to purge cache for everything in your Site or specific tags
• Use the runtime cache purging API to purge content by tags

When you purge cache for specific tags or all cache for your Site, it will clear both CDN cache and CoreCache (including Next.js ISR cache). This applies to cache purges through the Tilda dashboard and the runtime API (e.g. Next.js ISR revalidate).

On-demand Cache Purging

Tilda provides a runtime API to purge cached content by tags. This API is available in your application code through the global tilda.cache.purgeTags() function.

// Purge a single tag
await tilda.cache.purgeTags('products');

// Purge multiple tags
await tilda.cache.purgeTags(['product-123', 'category-456']);

// Example: Purge product cache after update
async function updateProduct(id, data) {
    await db.products.update(id, data);
    // Purge both the specific product and products list cache
    await tilda.cache.purgeTags(['products', `product-${id}`]);
}

The purgeTags() function accepts an array of strings as tags. When called, it will purge any cached content associated with those tags immediately from the Tilda CoreCache and kickoff purge across the CDN network.

Purge from CoreCache is immediate. And it takes less than 300ms in most cases to purge content from the CDN but can take longer based on network conditions and distance to the CDN PoP.