HTTP Caching Strategies

Effective caching reduces server load and improves performance. Here's how to implement HTTP caching correctly.

Cache-Control Header#

import express from 'express';

const app = express();

// Static assets - long cache with versioning
app.use('/static', express.static('public', {
  maxAge: '1y',
  immutable: true,
  setHeaders: (res) => {
    res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
  },
}));

// API responses - short cache
app.get('/api/products', (req, res) => {
  res.setHeader('Cache-Control', 'public, max-age=60, stale-while-revalidate=300');
  res.json(products);
});

// Private user data - no shared cache
app.get('/api/user/profile', (req, res) => {
  res.setHeader('Cache-Control', 'private, max-age=0, must-revalidate');
  res.json(userProfile);
});

// Never cache
app.get('/api/auth/token', (req, res) => {
  res.setHeader('Cache-Control', 'no-store');
  res.json({ token });
});

// Cache-Control directives:
// public - Can be cached by CDN/proxy
// private - Only browser cache
// max-age - Seconds until stale
// s-maxage - CDN-specific max-age
// no-cache - Must revalidate before using
// no-store - Don't cache at all
// immutable - Never changes
// must-revalidate - Must check when stale
// stale-while-revalidate - Serve stale while fetching fresh

ETag and Conditional Requests#

import crypto from 'crypto';

// Generate ETag from content
function generateETag(content: string | Buffer): string {
  return `"${crypto.createHash('md5').update(content).digest('hex')}"`;
}

// Middleware for ETag handling
function etag() {
  return (req: Request, res: Response, next: NextFunction) => {
    const originalJson = res.json.bind(res);

    res.json = function (body: any) {
      const content = JSON.stringify(body);
      const tag = generateETag(content);

      res.setHeader('ETag', tag);

      // Check If-None-Match header
      const ifNoneMatch = req.get('If-None-Match');
      if (ifNoneMatch === tag) {
        return res.status(304).end();
      }

      return originalJson(body);
    };

    next();
  };
}

app.use(etag());

// With Last-Modified
app.get('/api/article/:id', async (req, res) => {
  const article = await getArticle(req.params.id);

  res.setHeader('Last-Modified', article.updatedAt.toUTCString());

  // Check If-Modified-Since
  const ifModifiedSince = req.get('If-Modified-Since');
  if (ifModifiedSince) {
    const lastModified = new Date(article.updatedAt);
    const ifModifiedDate = new Date(ifModifiedSince);

    if (lastModified <= ifModifiedDate) {
      return res.status(304).end();
    }
  }

  res.json(article);
});

CDN Configuration#

// Vercel/Next.js headers
// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/static/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, max-age=31536000, immutable',
          },
        ],
      },
      {
        source: '/api/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, s-maxage=60, stale-while-revalidate=300',
          },
        ],
      },
    ];
  },
};

// Cloudflare Workers
export default {
  async fetch(request: Request) {
    const url = new URL(request.url);

    // Static assets
    if (url.pathname.startsWith('/static/')) {
      const response = await fetch(request);
      const newResponse = new Response(response.body, response);
      newResponse.headers.set(
        'Cache-Control',
        'public, max-age=31536000, immutable'
      );
      newResponse.headers.set('CDN-Cache-Control', 'max-age=31536000');
      return newResponse;
    }

    // API with cache
    if (url.pathname.startsWith('/api/')) {
      const cacheKey = new Request(url.toString(), request);
      const cache = caches.default;

      let response = await cache.match(cacheKey);

      if (!response) {
        response = await fetch(request);
        response = new Response(response.body, response);
        response.headers.set('Cache-Control', 's-maxage=60');

        // Cache in edge
        await cache.put(cacheKey, response.clone());
      }

      return response;
    }

    return fetch(request);
  },
};

Cache Invalidation#

// Versioned URLs
function assetUrl(path: string): string {
  const hash = getFileHash(path);
  return `/static/${hash}/${path}`;
}

// Or query string (less preferred)
function versionedUrl(path: string, version: string): string {
  return `${path}?v=${version}`;
}

// Purge CDN cache
async function purgeCache(urls: string[]) {
  // Cloudflare
  await fetch(
    `https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ files: urls }),
    }
  );
}

// Cache tags for grouped invalidation
app.get('/api/product/:id', (req, res) => {
  res.setHeader('Cache-Tag', `product-${req.params.id}, products`);
  res.setHeader('Cache-Control', 'public, s-maxage=3600');
  res.json(product);
});

// Purge by tag
async function purgeByTag(tag: string) {
  await fetch(
    `https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ tags: [tag] }),
    }
  );
}

Vary Header#

// Cache varies by Accept-Encoding
app.get('/api/data', (req, res) => {
  res.setHeader('Vary', 'Accept-Encoding');
  res.json(data);
});

// Cache varies by multiple headers
app.get('/api/content', (req, res) => {
  res.setHeader('Vary', 'Accept-Language, Accept-Encoding');
  res.json(localizedContent);
});

// Cache varies by cookie (careful - can bust cache)
app.get('/api/personalized', (req, res) => {
  res.setHeader('Vary', 'Cookie');
  res.setHeader('Cache-Control', 'private, max-age=60');
  res.json(personalizedContent);
});

// Best practice: separate cached and personalized content
// Don't: /api/page (returns different content based on auth)
// Do: /api/page/public + /api/page/user (separate endpoints)

Service Worker Caching#

// sw.js
const CACHE_NAME = 'v1';

const STATIC_ASSETS = [
  '/',
  '/styles.css',
  '/app.js',
  '/images/logo.png',
];

// Cache on install
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => {
      return cache.addAll(STATIC_ASSETS);
    })
  );
});

// Network first, fallback to cache
self.addEventListener('fetch', (event) => {
  if (event.request.url.includes('/api/')) {
    event.respondWith(
      fetch(event.request)
        .then((response) => {
          const clone = response.clone();
          caches.open(CACHE_NAME).then((cache) => {
            cache.put(event.request, clone);
          });
          return response;
        })
        .catch(() => caches.match(event.request))
    );
    return;
  }

  // Cache first for static assets
  event.respondWith(
    caches.match(event.request).then((cached) => {
      return cached || fetch(event.request);
    })
  );
});

// Stale-while-revalidate
self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.open(CACHE_NAME).then(async (cache) => {
      const cached = await cache.match(event.request);

      const fetchPromise = fetch(event.request).then((response) => {
        cache.put(event.request, response.clone());
        return response;
      });

      return cached || fetchPromise;
    })
  );
});

Cache Debugging#

// Add debug headers
app.use((req, res, next) => {
  res.on('finish', () => {
    console.log({
      url: req.url,
      cacheControl: res.getHeader('Cache-Control'),
      etag: res.getHeader('ETag'),
      vary: res.getHeader('Vary'),
    });
  });
  next();
});

// Check cache status (CDN-specific header)
// CF-Cache-Status: HIT, MISS, EXPIRED, BYPASS
// x-vercel-cache: HIT, MISS, STALE

// Browser DevTools
// Network tab shows cache status
// Disable cache checkbox for testing

Best Practices#

Headers:
✓ Use Cache-Control over Expires
✓ Set appropriate max-age values
✓ Use immutable for versioned assets
✓ Use stale-while-revalidate for API

Strategy:
✓ Version static assets in URL
✓ Use ETags for dynamic content
✓ Separate public and private content
✓ Plan cache invalidation

CDN:
✓ Use s-maxage for CDN-specific caching
✓ Implement cache tags
✓ Set up purge automation
✓ Monitor cache hit rates

Effective HTTP caching balances freshness and performance. Use long cache times with versioned URLs for static assets, short TTLs with stale-while-revalidate for APIs, and plan your cache invalidation strategy from the start. Monitor cache hit rates to ensure your strategy is working.