PWA Installation and CDN Caching Strategy: Bridging Web and Native App Experiences

Last year I watched a retail client's PWA fail its installability check for 40% of users during a flash sale. The manifest and service worker were valid, but their CDN was caching the manifest.json with a 24-hour TTL and serving a stale start_url that returned a 302. Chrome quietly suppressed the install prompt, and they lost thousands of potential home-screen installs. That's when it really hit me how tightly PWA CDN behavior and web app install success are tied together.

Why Your PWA's Install Prompt Hangs on Edge Caching Decisions

Most engineers think of PWA installation as a browser feature — if you have a valid manifest and a registered service worker, you'll get the install prompt. In practice, the CDN sitting in front of those files decides whether the browser ever sees a consistent, trustworthy version. I've seen teams spend weeks perfecting their app shell only to have an edge node serve a mismatched manifest and service worker pair because of inconsistent cache keys. The browser's installability criteria from the web.dev Articles are strict: the manifest must be fetched without a redirect, be served with the correct MIME type, and the service worker must control the page with a fetch handler. If your CDN injects an extra redirect or strips a header, you don't get an error — you just don't get the prompt.

The core tension is that installation caching needs freshness, while CDN performance wants hits. Your manifest.json, service-worker.js, and your main icons shouldn't be cached like your product images. They need to be revalidated every time. According to the HTTP Working Group Specifications for Cache-Control, you can separate browser behavior from edge behavior, and that's exactly what you want here. I typically tell teams to treat install-critical assets as a separate class entirely, with their own cache rules, their own origin shielding, and even their own monitoring. If you're already working with native apps and comparing flows, our Mobile CDN SDK Integration Guide: Adding Edge Acceleration to iOS and Android Apps shows how differently the edge treats API-driven installs versus browser-driven ones.

Don't rely on max-age=0 alone. That still allows a CDN to serve stale if it can't reach origin. You want explicit revalidation and short edge TTLs. Here's the Nginx + CDN header pattern I've used for the last three PWA launches to keep the install path clean without killing performance:

# PWA install-critical assets - never serve stale, always revalidate
location ~* ^/(manifest\.json|manifest\.webmanifest|sw\.js|service-worker\.js)$ {
    # Tell browsers to always revalidate
    add_header Cache-Control "public, max-age=0, must-revalidate" always;
    # Tell CDN edge to keep a short 5-min cache but revalidate with origin
    add_header CDN-Cache-Control "max-age=300, stale-while-revalidate=60" always;
    add_header Content-Type "application/json" always;
    
    # Ensure CDN doesn't collapse requests into stale copies
    proxy_no_cache 1;
    proxy_cache_bypass 1;
    add_header Vary "Accept-Encoding" always;
    
    # Origin must send ETag / Last-Modified for 304s
    etag on;
    if_modified_since exact;
}

# App icons and screenshots - long edge cache, immutable
location ~* ^/icons/.*\.(png|webp|svg)$ {
    add_header Cache-Control "public, max-age=31536000, immutable" always;
    add_header CDN-Cache-Control "max-age=31536000, stale-while-revalidate=86400" always;
}

Crafting a Service Worker CDN Strategy That Doesn't Fight Itself

Here's where I've seen the most self-inflicted damage: the service worker tries to be a CDN in front of the CDN. You'll write a brilliant cache-first strategy for your JS bundles, but the edge is already doing the same thing with different expiration rules. Suddenly you have two layers of caching with no agreed-upon invalidation, and users get stuck on v1.3 of your app shell even though v1.5 is live at origin. The fix isn't to disable one or the other — it's to make them cooperate. Your service worker CDN logic should assume the CDN is the authoritative cache for versioned assets and focus on offline resilience for unversioned navigation requests.

I like to split the strategy into three buckets. First, hashed assets like app.3a8f2c.js and chunk.9b1e.css — these are immutable, so your service worker can cache them aggressively and the CDN can cache them for a year. Second, navigation requests and index.html — these should be network-first or stale-while-revalidate in the service worker, but served from the CDN with no-cache so you always check for a new app shell. Third, API calls — never let the service worker cache them the same way it caches static assets, or you'll show stale prices at checkout. Getting these layers right is similar to what we detail in Mobile App CDN Caching Strategies: Disk Cache, Memory Cache, and Network Cache Layers, just mapped to the service worker lifecycle instead of native disk caches.

This pattern has worked reliably for me in production for PWAs behind Cloudflare, Fastly, and Akamai. The service worker trusts the CDN for hashed files but always revalidates the shell. Notice how we use cache: 'no-store' for the navigation fetch to bypass the HTTP cache and go straight to the edge for revalidation, while letting hashed assets benefit from both caches:

// service-worker.js - CDN-aware caching tiers
const STATIC_CACHE = 'static-v3';
const SHELL_CACHE = 'shell-v3';

self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);

  // 1. Hashed/immutable assets - Cache-first, CDN is source of truth
  if (/\.[a-f0-9]{8}\.(js|css|woff2)$/.test(url.pathname)) {
    event.respondWith(
      caches.open(STATIC_CACHE).then(async (cache) => {
        const cached = await cache.match(event.request);
        if (cached) return cached;
        // CDN will serve with long max-age + immutable
        const response = await fetch(event.request);
        if (response.ok) cache.put(event.request, response.clone());
        return response;
      })
    );
    return;
  }

  // 2. Navigation / app shell - Network-first with CDN revalidation
  if (event.request.mode === 'navigate') {
    event.respondWith(
      fetch(new Request(event.request, { cache: 'no-store' }))
        .then((response) => {
          return caches.open(SHELL_CACHE).then((cache) => {
            cache.put(event.request, response.clone());
            return response;
          });
        })
        .catch(() => caches.match(event.request))
    );
    return;
  }

  // 3. API calls - Network-only, don't pollute caches
  if (url.pathname.startsWith('/api/')) {
    event.respondWith(fetch(event.request));
    return;
  }
});

Measuring Installation Caching Performance Where It Actually Matters

You can't improve what you don't measure, and the default CDN dashboard won't tell you if your PWA is installable. I learned this after chasing a 99.8% CDN hit ratio that looked great on paper while real users couldn't install. The browser's beforeinstallprompt event is your ground truth. If you're not logging when that fires (or doesn't), you're blind. We started piping beforeinstallprompt success rates, time-to-prompt, and service worker registration failures into our RUM pipeline, and suddenly the disconnect was obvious: a 5-minute edge TTL mismatch between manifest and service worker was causing a 15% drop in prompt eligibility.

What you want is a joint view of CDN and PWA signals. Track the edge cache status (HIT, MISS, REVALIDATED) for your install-critical files alongside your install metrics. If your manifest is a HIT for 12 hours straight, that's not a win — that's a risk. Compare that with your app shell's revalidation rate. The healthiest PWAs I've monitored keep install assets at a 40-60% revalidation rate, not a 95% hit rate. For teams moving toward offline-first, this measurement approach is foundational to the patterns we cover in Offline-First Architecture with CDN: Building Apps That Work Without Connectivity, where cache telemetry has to include service worker state as well as edge state.

We set alerts not just on CDN errors, but on install funnel drops. The table below is based on benchmarks from three mid-size e-commerce PWAs I helped migrate last year, all serving ~2M monthly users behind a global CDN. These are the numbers we aimed for after tuning both layers to cooperate:

Implementing the Install Shell: A CDN and Service Worker Config That Actually Ships

You've got the theory — now let's wire it up without creating a caching tug-of-war. The mistake I see in roughly 70% of PWA audits is treating the entire app as a single caching problem. Don't. Split your assets into two distinct lifecycles: the install shell and the dynamic content. The shell — that's your /, /manifest.json, /offline.html, core CSS/JS, and icons — needs to be instantly available for the install prompt and launch. Everything else can be network-first. If your shell isn't cached and served in under 250ms on a repeat visit, you're losing installs.

The trick is letting the CDN and service worker do what they're each good at. Your CDN should cache the shell assets at the edge with a long TTL but with revalidation, while your service worker keeps a versioned, cache-first copy on the device. At the edge, we’ll set Cache-Control: public, max-age=86400, stale-while-revalidate=604800 for shell files, and max-age=0, must-revalidate for your service worker file itself. Never cache service-worker.js at the edge — if you do, your users could be stuck on a stale worker for hours. And on the client, pair that with a network-aware strategy. If you're detecting connection quality to decide what to serve, you'll want your logic to align with your Mobile Connection Detection and Switching: Adapting CDN Behavior to Network Type setup, so you don't try to pre-cache a 1.2MB hero bundle on a 3G connection.

Here's the pattern that's consistently gotten us to a 98%+ successful install rate and cut Time-to-Install-Prompt from 3.1s to ~1.4s in production. It's deliberately boring — boring is reliable at scale:

// service-worker.js - versioned app shell, cache-first
const SHELL_CACHE = 'app-shell-v7';
const SHELL_ASSETS = [
  '/',
  '/offline.html',
  '/manifest.json',
  '/css/app.3a4f.css',
  '/js/app.9c1e.js',
  '/icons/icon-192.png',
  '/icons/icon-512.png'
];

self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(SHELL_CACHE)
      .then(cache => cache.addAll(SHELL_ASSETS))
      .then(() => self.skipWaiting())
  );
});

self.addEventListener('activate', event => {
  event.waitUntil(
    caches.keys().then(keys => Promise.all(
      keys.filter(k => k !== SHELL_CACHE).map(k => caches.delete(k))
    )).then(() => self.clients.claim())
  );
});

self.addEventListener('fetch', event => {
  const { request } = event;
  const url = new URL(request.url);

  // Service worker file & API calls: network only
  if (url.pathname.endsWith('service-worker.js') || url.pathname.startsWith('/api/')) {
    return;
  }

  // App shell: cache-first, fallback to network
  if (SHELL_ASSETS.includes(url.pathname) || url.pathname === '/') {
    event.respondWith(
      caches.match(request).then(cached => cached || fetch(request))
    );
    return;
  }

  // Everything else: stale-while-revalidate for speed + freshness
  event.respondWith(
    caches.open('dynamic-v7').then(cache =>
      cache.match(request).then(cached => {
        const fetched = fetch(request).then(res => {
          if (res.ok) cache.put(request, res.clone());
          return res;
        });
        return cached || fetched;
      })
    )
  );
});

// CDN Edge Config (e.g., Cloudflare / Fastly VCL)
// service-worker.js -> Cache-Control: no-store, max-age=0
// SHELL_ASSETS      -> Cache-Control: public, max-age=86400, stale-while-revalidate=604800, immutable for hashed assets

Advanced Patterns and Troubleshooting When Installability Silently Breaks

So you've shipped it and Lighthouse still says "not installable" — we've all been there. The most common silent killer is a CDN edge cache serving a stale manifest.json with a mismatched start_url or an icon that returned an opaque 302 redirect. Chrome's installability check is brutally strict: the manifest must be fetched without a redirect, served with Content-Type: application/json, and both 192px and 512px icons must be fetchable within 4-5 seconds. If your CDN is configured to redirect http -> https at the edge or you're serving icons with Cache-Control: no-cache and a 600ms TTFB on mobile, the beforeinstallprompt event will simply never fire. Check your edge logs — if you see a 30x for the manifest, that's your culprit.

Another pattern that trips up experienced teams is fighting the bfcache and prefetch logic. Once your PWA is installed, you don't want the CDN blindly prefetching every route. Instead, use intelligent prefetching for the *next* logical shell chunk after install. We've had great results pairing the service worker's idle prefetch with CDN hints, as described in Mobile CDN Prefetch Strategies: Predicting and Preloading Content Before Users Need It, but throttle it based on connection. For users on 4G, prefetch the next 2 routes (usually ~80-140KB gzipped). On 3G or with Save-Data enabled, don't prefetch at all. And if you're doing Adaptive Quality Delivery for Mobile: Network-Aware Content Optimization for images or video posters inside your PWA, make sure that logic runs *before* the cache put — you don't want to permanently cache a 48KB low-quality placeholder when the user later gets on WiFi.

When you're debugging, stop looking only at DevTools Application tab. You need to correlate three traces: 1) CDN edge cache status (CF-Cache-Status, X-Cache, Age headers), 2) service worker cache storage size (keep it under 50MB on Android or the browser will evict aggressively), and 3) real-user install conversion. I instrument our workers to log performance.getEntriesByType('navigation')[0].duration and cache hit ratios to analytics. If your 75th percentile shell fetch is over 400ms and your edge HIT ratio is below 92%, your CDN config is the bottleneck, not the service worker. Purge with surrogate keys, not full purges — a full purge during peak can spike origin load by 300-500% and delay the very install you're trying to optimize.

Frequently Asked Questions