CDN & Caching

Sherpa.sh provides high-performance content delivery and caching through our global CDN infrastructure, powered by bunny.net’s industry-leading network. Our CDN automatically optimizes content delivery for your applications while providing flexible caching controls for different deployment scenarios.

Performance Advantages on Sherpa.sh

Global Network Infrastructure

Our CDN delivers industry-leading performance with:

• 200+ Points of Presence (PoPs) strategically located worldwide
• 25.45ms average global latency - significantly lower than competitors
• 95% cache hit ratio ensuring optimal content delivery
• 100Gbit uplinks with NVMe storage at major PoPs

Regional Performance Comparison

Sherpa.sh CDN consistently outperforms legacy CDN providers across all major regions:

• North America: 15-20ms average latency
• Europe: 18-25ms average latency
• Asia-Pacific: 22-28ms average latency
• Latin America: 25-35ms average latency
• Africa: 30-45ms average latency

How Our Caching Works

Framework-Aware Caching

When deploying full-stack frameworks, Sherpa.sh intelligently listens to your framework’s default cache-control headers and configures caching settings accordingly. We optimize these settings based on established best practices for each framework.

Next.js Example:

Below you will find and example of how our framework aware caching performs on a nextjs app. This intelligent caching occurs for all our supported frameworks

Static Assets

• Path: /_next/static/*
• Cache-Control: public, max-age=31536000, immutable
• Purpose: Cached for 1 year to improve performance.

API Routes

• Path: /api/*
• Cache-Control: no-cache, no-store, must-revalidate
• Purpose: Not cached by default to ensure data is always fresh.

Server-side Rendered Pages

• Cache-Control: public, max-age=0, must-revalidate
• Purpose: Short cache life with revalidation to update content dynamically.

Static Pages

• Cache-Control: public, max-age=3600, stale-while-revalidate=86400
• Purpose: Cached with background updates to allow fresh content while ensuring availability.

Our system automatically recognizes these patterns and applies optimal caching strategies:

• Static assets: Long-term caching with immutable flag
• API endpoints: Bypassed from CDN cache
• Dynamic pages: Smart caching with background refresh
• Image optimization: Automatic format conversion and caching

Default Caching Behavior

By default Sherpa.sh always respects the Cache-Control and Expire headers returned by the application. If no headers are present, no caching in the CDN will occur. Most frameworks (like nextjs, will automatically return the appropriate headers for you) while some others (like Sveltekit) require you to explicitly return them.

Below is a list of extensions that are cachable for fullstack frameworks:

List of cacheable extensions:

3g2	3gp	7z	ai	asf	avi	avif	apk
bin	bat	bmp	bz2	class	css	csv	dat
doc	docx	dll	dmg	ejs	eot	eps	exe
flac	flv	heic	gif	gz	ico	iso	jar
jpg	jpeg	js	m3u8	m4u	mid	midi	mkv
mp3	mp4	mpa	mpg	odt	ogg	otf	pdf
pict	pls	png	ppt	pptx	ps	psd	rar
srt	svg	svg2	swf	tar	tif	tiff	ttf
vob	webm	webp	woff	woff2	wav	wma	xls
xlsx	zip	zst	ts	txt	yuv

MIME types that will not be cached:

text/html	application/json	application/xml

Default caching behavior of static builds

If you have enabled static site generation in your build settings, Sherpa.sh will default to caching everything. You can control how long items are cached with the cache-control and expire headers.

Global Key-Value Store

Sherpa.sh includes a global KV store that serves as the backend cache for various frameworks. This is separate from our CDN caching layer and provides:

• Low-latency data access across all deployment regions
• Automatic replication for high availability
• Framework integration for session storage, API caching, and more
• Edge computing support for serverless functions

Note: This KV store is distinct from CDN caching and focuses on application-level data storage.

Docker Deployment Caching

Manual Cache Header Configuration

When deploying Docker containers, you must set cache-control headers manually since containerized applications don’t have framework-specific defaults.

Setting Cache Headers in Docker Applications:

# Example: Node.js Express application
FROM node:18-alpine

COPY . .

RUN npm install

EXPOSE 3000

CMD ["node", "server.js"]

// server.js - Manual header configuration

app.use(
  '/static',
  express.static('public', {
    maxAge: '1y',
    etag: false,
    lastModified: false
  })
);

app.get('/api/*', (req, res) => {
  res.set('Cache-Control', 'no-store');
  // API logic here
});

app.get('/', (req, res) => {
  res.set('Cache-Control', 'public, max-age=3600, stale-while-revalidate=86400');
  res.send('Hello World');

Cache-Control Headers Reference

Understanding when and how to use different cache-control directives is crucial for optimal performance. Here’s a comprehensive guide:

Cache-Control Policy Guidelines

1. Static Assets (CSS, JS, Images with Versioning):

• Cache-Control: public, max-age=31536000, immutable

2. HTML Pages with Dynamic Content:

• Cache-Control: public, max-age=3600, stale-while-revalidate=86400

3. API Responses That Change Frequently:

• Cache-Control: public, max-age=300, must-revalidate

4. Sensitive or User-Specific Content:

• Cache-Control: private, max-age=0, no-cache

5. Content That Should Never Be Cached:

• `Cache-Control: no-store, no-cache, must

Key Directives Explained:

• public: Cacheable by CDN and browsers
• private: Only cacheable by browsers
• max-age: Cache lifetime in seconds
• stale-while-revalidate: Serve stale content while updating
• immutable: Content never changes (perfect for versioned assets)
• no-store: Never cache anywhere

For detailed information about HTTP caching headers, refer to the MDN Cache-Control documentation.

CDN Configuration Options

Automatic CDN Deployment

Sherpa.sh automatically places a CDN in front of every deployment by default. This provides:

• Global content distribution across 200+ edge locations
• Automatic SSL termination and certificate management
• DDoS protection and security filtering
• Image optimization and format conversion

Docker CDN Recommendations

For Docker deployments, you can disable CDN if needed, though this is typically recommended only when:

• You’re unsure whether your framework sets appropriate cache-control headers
• Your application requires direct server connections
• You’re implementing custom caching logic

Best Practice: Keep CDN enabled and configure proper cache headers instead of disabling CDN entirely.

Advanced Caching Features

Sherpa.sh automatically implements sophisticated caching optimizations behind the scenes to maximize performance and reliability. Here’s what happens under the hood when your application is deployed.

Smart Cache Intelligence

Automatic File Type Detection

When your application serves content, our CDN automatically analyzes each request and determines the optimal caching strategy:

What happens internally:

• File extensions and MIME types are analyzed in real-time
• Static assets (CSS, JS, images) receive aggressive caching
• Dynamic endpoints are intelligently bypassed
• Binary files are optimized for streaming delivery

Query String Normalization

Our system automatically sorts query parameters to improve cache hit rates:

# These requests are treated as identical:
GET /api/resize?width=200&height=100&format=webp
GET /api/resize?format=webp&height=100&width=200
GET /api/resize?height=100&width=200&format=webp
# Result: Single cached response serves all three requests

Benefits for developers:

• Higher cache hit rates without code changes
• Reduced origin server load
• Consistent response times regardless of parameter order

Intelligent Cache Variations

Browser Capability Detection

The CDN automatically detects browser capabilities and serves optimized content:

# Modern browser request:
# Accept: image/avif,image/webp,image/*
# Serves: optimized AVIF format (90% smaller) Cache-Key: image.jpg:avif-support

# Legacy browser request: 
# Accept: image/*
# Serves: standard JPEG format Cache-Key: image.jpg:no-avif-support

Device-Aware Caching

Content is automatically optimized based on device characteristics:

# Mobile device:User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS...) # Serves: Mobile-optimized images and CSS
# Desktop device:User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS...)  # Serves: High-resolution desktop assets

Geographic Optimization

Content delivery is optimized based on user location:

# User in Europe:
# Serves from Amsterdam PoP (12ms latency)
# Includes region-specific optimizations

# User in Asia:
# Serves from Tokyo PoP (8ms latency)
# Applies Asia-Pacific performance tweaks

Resilient Content Delivery

Error Response Protection

The CDN automatically protects your origin server from cascading failures:

# Origin server returns 500 error
HTTP/1.1 500 Internal Server Error

# CDN behavior:
1. Caches error response for 5 seconds
2. Serves cached error to subsequent requests
3. Prevents origin server overload during incidents
4. Automatically retries after cache expiration

Stale Content Serving

When your origin server is unreachable or updating, users still receive content:

# Scenario 1: Origin server offline
Origin Status: Connection refused
CDN Response: Serves last known good version Cache-Control: stale-while-revalidate

# Scenario 2: Content being updated
Origin Status: Updating cache in background
CDN Response: Serves current cached version immediately
Update Status: New content ready for next request

Real-world impact:

• 99.9% uptime even during origin server issues
• Zero-downtime deployments
• Seamless user experience during maintenance

Performance Optimizations

Video Content Handling

Large media files receive special treatment:

# Video file request with byte range:
GET /video.mp4Range: bytes=1000000-2000000
# CDN behavior:
1. Splits file into 5MB chunks during first request
2. Caches chunks independently
3. Serves partial content without hitting origin
4. Enables video scrubbing for uncached content

Multi-Layer Caching

Your content benefits from multiple caching layers:

Request Flow:
Browser Cache (immediate)
 ↓ (cache miss)Edge PoP Cache (5-25ms)
    ↓ (cache miss)  Regional Cache (25-50ms)
        ↓ (cache miss) Origin Server (50-200ms)

Developer Benefits

Zero Configuration Required

All optimizations work automatically:

• No cache headers to configure for frameworks
• Automatic performance improvements
• Self-tuning based on traffic patterns

Built-in Best Practices

The system implements industry standards:

• Proper cache invalidation strategies
• Optimal TTL values for different content types
• Automatic security header injection

Troubleshooting Common Scenarios

Low Cache Hit Rates

The system automatically adjusts when hit rates drop:

• Analyzes traffic patterns
• Adjusts cache TTL values
• Optimizes query string handling

Content Update Delays

Stale content serving ensures smooth updates:

• New content propagates in background
• Users never see loading states
• Automatic cache purging when needed

This intelligent caching layer operates transparently, requiring no configuration while delivering maximum performance benefits for your applications.