StackPractices
intermediate Por Mathias Paulenko

Service Worker Offline Caching para PWA en JavaScript

Sirve tu aplicación web sin conexión con Service Workers y la Cache API: precaché, estrategias de caché en runtime y página de respaldo.

Temas: frontend

Visión General

Un usuario abre tu app en un túnel, en un avión o con un Wi-Fi de hotel que se cae cada treinta segundos — y en lugar de tu interfaz ve la página de error del navegador. Un Service Worker lo evita: se registra desde tu página y luego corre en su propio hilo, donde intercepta cada petición que hace la app y responde desde una caché que tú controlas.

La receta de abajo cubre el montaje completo: registrar el worker desde main.js, precachear el app shell durante install, tres estrategias en runtime (cache-first, network-first, stale-while-revalidate), borrar cachés viejas en activate, una página de respaldo offline y reintentar un envío de formulario con Background Sync. Todo es JavaScript plano — sin framework y sin Workbox.

Cuándo Usar

Usa un Service Worker cuando tu app deba seguir funcionando sin una conexión fiable:

  • Las visitas repetidas deben renderizar al instante incluso con redes lentas: un recurso cacheado gana a la red siempre.
  • Estás construyendo una PWA instalable y el soporte offline es parte del trato.
  • Usuarios móviles con conexiones inestables entran a tu app a diario, y una pantalla en blanco te cuesta usuarios.
  • Tu origen sirve los mismos archivos estáticos una y otra vez y quieres que el cliente absorba ese tráfico.

Sáltalo cuando el contenido no tolere nada de desfase: paneles en vivo, cotizaciones, saldos bancarios. Ahí una respuesta cacheada vieja es peor que un error honesto. Los sitios renderizados en servidor que siempre sirven datos por usuario tampoco ganan mucho. Cachearías el shell pero seguirías necesitando la red para el cuerpo. Y recuerda el requisito duro: los Service Workers solo se registran en contexto seguro, o sea HTTPS en producción o localhost en desarrollo.

Solución

Registrar un service worker

La página registra /sw.js una sola vez, dentro del evento load para que el registro no compita con el primer pintado. Si el navegador no soporta workers, nada se rompe — el if convierte el soporte offline en mejora progresiva.

// main.js
if ("serviceWorker" in navigator) {
    window.addEventListener("load", () => {
        navigator.serviceWorker
            .register("/sw.js")
            .then((reg) => console.log("SW registrado:", reg.scope))
            .catch((err) => console.error("Error al registrar SW:", err));
    });
}

Estrategia cache-first para recursos estáticos

Precachea el app shell durante install y luego responde cada GET desde caché antes de tocar la red. Fíjate en el .catch() final: para peticiones de navegación devuelve la página offline, y para recursos que fallan devuelve Response.error() para que el fetch rechace como un fallo de red normal. Devolver undefined ahí haría que respondWith() lanzara un error.

// sw.js
const CACHE_NAME = "app-v1";
const STATIC_ASSETS = [
    "/",
    "/index.html",
    "/styles.css",
    "/app.js",
    "/offline.html",
    "/favicon.ico"
];

self.addEventListener("install", (event) => {
    event.waitUntil(
        caches.open(CACHE_NAME)
            .then((cache) => cache.addAll(STATIC_ASSETS))
            .then(() => self.skipWaiting())
    );
});

self.addEventListener("activate", (event) => {
    event.waitUntil(
        caches.keys()
            .then((keys) => {
                return Promise.all(
                    keys
                        .filter((key) => key !== CACHE_NAME)
                        .map((key) => caches.delete(key))
                );
            })
            .then(() => self.clients.claim())
    );
});

self.addEventListener("fetch", (event) => {
    if (event.request.method !== "GET") return;

    event.respondWith(
        caches.match(event.request).then((cached) => {
            if (cached) return cached;

            return fetch(event.request)
                .then((response) => {
                    if (!response || response.status !== 200) return response;

                    const clone = response.clone();
                    caches.open(CACHE_NAME).then((cache) => {
                        cache.put(event.request, clone);
                    });

                    return response;
                })
                .catch(() => {
                    if (event.request.mode === "navigate") {
                        return caches.match("/offline.html");
                    }
                    return Response.error();
                });
        })
    );
});

Estrategia stale-while-revalidate

La estrategia más rápida en percepción: sirve la copia cacheada de inmediato y refresca la caché en segundo plano para la próxima visita. El usuario a veces ve la versión anterior durante una carga. Aceptable para recursos que cambian seguido pero no de forma crítica.

// sw.js
const CACHE_NAME = "swr-v1";

self.addEventListener("install", () => {
    self.skipWaiting();
});

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

self.addEventListener("fetch", (event) => {
    if (event.request.method !== "GET") return;

    event.respondWith(
        caches.open(CACHE_NAME).then((cache) => {
            return cache.match(event.request).then((cached) => {
                const fetchPromise = fetch(event.request)
                    .then((response) => {
                        if (response && response.status === 200) {
                            cache.put(event.request, response.clone());
                        }
                        return response;
                    })
                    .catch(() => cached);

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

Network-first para datos de API con respaldo en caché

Las respuestas de API deben mantenerse frescas, así que intenta la red primero y escribe las respuestas exitosas en una caché dedicada. Cuando la red cae, el usuario recibe la última respuesta buena conocida, o un error JSON limpio si todavía no había nada cacheado.

// sw.js
const API_CACHE = "api-v1";
const STATIC_CACHE = "static-v1";

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

    if (event.request.method !== "GET") return;

    if (url.pathname.startsWith("/api/")) {
        event.respondWith(
            fetch(event.request)
                .then((response) => {
                    if (response.status === 200) {
                        const clone = response.clone();
                        caches.open(API_CACHE).then((cache) => {
                            cache.put(event.request, clone);
                        });
                    }
                    return response;
                })
                .catch(() => {
                    return caches.match(event.request).then((cached) => {
                        if (cached) return cached;
                        return new Response(
                            JSON.stringify({ error: "Offline" }),
                            { headers: { "Content-Type": "application/json" } }
                        );
                    });
                })
        );
        return;
    }

    event.respondWith(
        caches.match(event.request).then((cached) => {
            return cached || fetch(event.request).then((response) => {
                const clone = response.clone();
                caches.open(STATIC_CACHE).then((cache) => {
                    cache.put(event.request, clone);
                });
                return response;
            }).catch(() => caches.match("/offline.html"));
        })
    );
});

Limpieza de caché en la activación

Cada despliegue que sube CACHE_NAME deja la caché anterior atrás. El manejador activate es el lugar correcto para borrar todo lo que no esté en la lista permitida: corre una sola vez, después de que el worker viejo cede el control.

self.addEventListener("activate", (event) => {
    const allowedCaches = ["static-v2", "api-v2"];

    event.waitUntil(
        caches.keys().then((cacheNames) => {
            return Promise.all(
                cacheNames.map((cacheName) => {
                    if (!allowedCaches.includes(cacheName)) {
                        console.log("Eliminando caché antigua:", cacheName);
                        return caches.delete(cacheName);
                    }
                })
            );
        }).then(() => self.clients.claim())
    );
});

Background sync para envío de formularios sin conexión

Cuando el usuario envía un formulario sin conexión, guarda el payload localmente, registra un evento sync y deja que el worker lo reintente cuando vuelva la conectividad. Si el navegador no tiene SyncManager (Safari no lo implementa), el código recurre a un fetch normal.

// main.js
async function submitForm(data) {
    if ("serviceWorker" in navigator && "SyncManager" in window) {
        const reg = await navigator.serviceWorker.ready;
        await storeFormData(data);
        reg.sync.register("submit-form");
    } else {
        await fetch("/api/submit", {
            method: "POST",
            body: JSON.stringify(data)
        });
    }
}

// sw.js — carga los helpers primero: importScripts("/db.js")
self.addEventListener("sync", (event) => {
    if (event.tag === "submit-form") {
        event.waitUntil(replayFormSubmission());
    }
});

async function replayFormSubmission() {
    const stored = await getStoredFormData();
    for (const data of stored) {
        const res = await fetch("/api/submit", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(data)
        });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        await removeStoredFormData(data.id);
    }
}

Los helpers storeFormData, getStoredFormData y removeStoredFormData necesitan un almacén real. localStorage no es accesible desde un worker, así que IndexedDB hace el trabajo: una implementación mínima sería esta:

// db.js — compartido: <script> en la página, importScripts("/db.js") en sw.js
function openDB() {
    return new Promise((resolve, reject) => {
        const req = indexedDB.open("offline-forms", 1);
        req.onupgradeneeded = () =>
            req.result.createObjectStore("queue", { keyPath: "id", autoIncrement: true });
        req.onsuccess = () => resolve(req.result);
        req.onerror = () => reject(req.error);
    });
}

async function storeFormData(data) {
    const db = await openDB();
    return new Promise((resolve, reject) => {
        const tx = db.transaction("queue", "readwrite");
        tx.objectStore("queue").add(data);
        tx.oncomplete = resolve;
        tx.onerror = () => reject(tx.error);
    });
}

async function getStoredFormData() {
    const db = await openDB();
    return new Promise((resolve, reject) => {
        const req = db.transaction("queue", "readonly")
            .objectStore("queue").getAll();
        req.onsuccess = () => resolve(req.result);
        req.onerror = () => reject(req.error);
    });
}

async function removeStoredFormData(id) {
    const db = await openDB();
    return new Promise((resolve, reject) => {
        const tx = db.transaction("queue", "readwrite");
        tx.objectStore("queue").delete(id);
        tx.oncomplete = resolve;
        tx.onerror = () => reject(tx.error);
    });
}

Un detalle que conviene notar en replayFormSubmission: fetch solo rechaza por fallo de red, no por errores HTTP. El chequeo de res.ok evita que un 500 borre un registro de la cola. El evento sync simplemente se volverá a disparar más tarde y reintentará.

Explicación

Un Service Worker es un proxy programable que vive entre tu página y la red. Una vez registrado corre en un hilo separado — sin acceso al DOM ni a localStorage — y cada petición de las páginas controladas pasa por su manejador fetch, donde decides si la respuesta sale de caché, de la red o de un respaldo.

flowchart diagram: Req[

El ciclo de vida tiene cuatro fases que importan:

  • Install se dispara en el primer registro (y en cada actualización). Aquí precacheas el app shell con cache.addAll(): un solo fetch fallido aborta toda la instalación, así que limita la lista a lo que la página realmente necesita. skipWaiting() permite que el worker nuevo salte directo sobre la fase de espera.
  • Activate se dispara después de install, cuando ya ningún worker viejo controla un cliente. Borra las cachés obsoletas aquí y llama clients.claim() para que el worker tome el control de las pestañas abiertas de inmediato en vez de esperar a la próxima carga.
  • Fetch se dispara por cada petición que hace la página. Revisa event.request y elige la estrategia que encaje: recursos estáticos con cache-first, llamadas a API con network-first, recursos que cambian seguido con stale-while-revalidate.
  • Sync se dispara cuando vuelve la conectividad tras un reg.sync.register(). El navegador puede dispararlo incluso con la página cerrada (esa es la gracia) pero Safari nunca lo implementó, así que trátalo como mejora progresiva.

Las estrategias difieren sobre todo en lo que sacrifican:

  • Cache-first cambia frescura por velocidad. Perfecto para recursos versionados o con hash; peligroso para un app.js sin versión, que servirá código viejo hasta que cambie CACHE_NAME.
  • Network-first mantiene los datos frescos y sostiene una copia de respaldo sin hacer ruido. El costo es pagar la latencia de red en cada petición online aunque exista una respuesta cacheada.
  • Stale-while-revalidate sirve la copia cacheada al instante y revalida en segundo plano: la mejor velocidad percibida, pero el usuario ve la versión anterior hasta la próxima carga.

Tres cosas muerden a los equipos en producción:

Cuota de almacenamiento. La Cache API comparte la cuota del origen con IndexedDB y demás almacenamiento. Puedes inspeccionarla con navigator.storage.estimate(), y bajo presión el navegador puede expulsar todos los datos del origen. navigator.storage.persist() pide almacenamiento durable (Chrome lo concede según la interacción del usuario). Por eso la lista de precaché debe quedarse chica: un addAll() fallido o inflado frena cada instalación.

Respuestas opacas. Las peticiones cross-origin respondidas sin CORS — fuentes de CDN, widgets de terceros — vuelven como respuestas opacas con status 0 y cuerpo ilegible. Los chequeos de status === 200 en los ejemplos las saltan a propósito. Puedes cachear respuestas opacas (se replican bien), pero inflan tu cuota y no puedes validar qué guardas — el mismo tipo de equilibrio de almacenamiento con expiración que cubre la receta de LocalStorage con expiración TTL, solo que con menos visibilidad.

Actualizaciones y TTL. Los navegadores comparan byte a byte sw.js en las navegaciones (como máximo una vez cada 24 horas) e instalan el worker nuevo cuando los bytes difieren. El worker viejo conserva el control hasta que su último cliente se cierra. Por eso existen skipWaiting() y clients.claim(), y por eso importa subir CACHE_NAME en cada despliegue: el manejador activate solo limpia las cachés que no coinciden con la nueva lista permitida.

Si mantener un worker escrito a mano crece hasta ser un proyecto en sí mismo, mira Workbox: la librería de Google envuelve todas estas estrategias, genera el manifiesto de precaché en tiempo de build y maneja el versionado por ti. Los conceptos son los mismos mostrados aquí. Para el equivalente en servidor de este mismo equilibrio (mirar el almacén primero y luego el origen) el patrón cache-aside es la misma idea aplicada a datos de backend.

Variantes

Elige por tipo de petición, no por aplicación: un solo worker suele combinar varias de estas:

EstrategiaMejor paraActualidadSin conexión
Cache-firstRecursos estáticos (CSS, JS, fuentes)BajaCompleta
Network-firstDatos de API, contenido dinámicoAltaRespaldo
Stale-while-revalidateImágenes, fuentes, actualizaciones frecuentesMediaCompleta
Cache-onlyPáginas offline, shell precacheadoNingunaCompleta
Network-onlyAnalítica, llamadas no-cacheablesAltaNinguna

Lo que funciona

  • Precachea solo lo que el app shell no puede renderizar sin: offline.html, CSS y JS core. Una lista addAll() gigante falla con el primer archivo que falte y frena cada instalación.
  • Ajusta la estrategia al dato: cache-first para recursos con hash o versión en la URL, network-first para cualquier cosa que el usuario espera ver actualizada.
  • Borra las cachés viejas en activate, siempre. Las limpiezas saltadas engordan el almacenamiento en silencio hasta que llega la expulsión por cuota. Y los navegadores expulsan el origen entero, no una caché a la vez.
  • Protege el manejador fetch con event.request.method !== "GET". POST/PUT/DELETE deben ir a la red intactas, y cachear sus respuestas está mal de todos modos.
  • Dale a las navegaciones una página offline de verdad. Un offline.html con estilo y un enlace de reintento se lee infinitamente mejor que la pantalla de error del navegador.
  • Versiona los nombres de caché (static-v1 → static-v2) en cada despliegue que cambie contenido cacheado; la limpieza de activate hace la migración gratis.
  • En desarrollo, skipWaiting() + clients.claim() junto al “Update on reload” de DevTools te ahorra preguntarte por qué el worker viejo sigue vivo.

Errores Comunes

  • No versionar los nombres de caché, así que los usuarios se quedan con contenido viejo para siempre. El worker se actualiza pero nada invalida lo que cacheó.
  • Precachear demasiado en install: cada entrada de STATIC_ASSETS es una petición de red, y un solo 404 aborta toda la instalación.
  • Terminar sin devolver respuesta. Si el .catch() de un manejador fetch no retorna una Response (o una promesa de una), respondWith() lanza error: devuelve siempre la página offline o Response.error().
  • Cachear respuestas POST u otras que no sean GET. No son idempotentes, y la Cache API lanza error en un cache.put() de no-GET de todos modos.
  • Cachear respuestas opacas por accidente y preguntarse adónde fue la cuota. No puedes inspeccionarlas, solo confiar en ellas.
  • Asumir que Background Sync es universal. Safari nunca incluyó SyncManager; haz feature-detect o los usuarios de iOS pierden la cola offline en silencio.
  • Olvidar HTTPS. El registro solo funciona en contextos seguros: localhost está exento, un dominio de staging en HTTP plano no.

Ver También

Preguntas frecuentes

¿Cómo fuerzo la actualización del service worker?

Sube la versión de caché (static-v1 → static-v2) y cambia un byte en sw.js. El navegador detecta la diferencia en la próxima navegación, instala el worker nuevo y (si llamaste skipWaiting() y clients.claim()) el manejador activate limpia las cachés viejas de inmediato en vez de esperar a que se cierren las pestañas.

¿Pueden los service workers acceder a localStorage?

No — los workers no tienen window ni localStorage. Dentro del worker tus opciones son la Cache API para respuestas HTTP o IndexedDB para datos estructurados (los helpers de db.js de arriba usan exactamente eso).

¿Cómo depuro un service worker?

Chrome DevTools → Application → Service Workers muestra los workers registrados, te deja desregistrarlos, y tiene los toggles "Update on reload" y "Bypass for network". La pestaña Console muestra los logs del worker.

¿Cuál es la diferencia entre skipWaiting y clients.claim?

skipWaiting() corre dentro de install y le dice al worker nuevo que se active sin esperar a que las pestañas abiertas se cierren. clients.claim() corre dentro de activate y hace que ese worker activo controle las pestañas existentes de inmediato. Normalmente quieres ambos para actualizaciones instantáneas.

¿Puedo probar el comportamiento offline sin quedarme sin conexión?

Sí: Chrome DevTools → Network → checkbox Offline simula una conexión caída. Para cobertura automatizada, context.setOffline(true) de Playwright hace lo mismo dentro de CI.