Home / Frontend / Aplicaciones web instalables y sin conexión con service workers
Aplicaciones web instalables y sin conexión con service workers

Aplicaciones web instalables y sin conexión con service workers

19 November 2026 · 28 min de lectura ··

Qué vamos a construir y por qué importa

Una aplicación web progresiva, o PWA, es un sitio web que se comporta como una aplicación: se puede instalar en el escritorio o en la pantalla de inicio del móvil, arranca en una ventana propia, responde aunque la red falle y se actualiza sin pasar por ninguna tienda. No es un framework ni un producto concreto, sino un conjunto de capacidades del navegador que se combinan sobre HTML, CSS y JavaScript corrientes.

En este tutorial construiremos desde cero una pequeña aplicación de notas de lectura llamada “Marcapáginas”. Empezaremos con tres archivos estáticos y los iremos convirtiendo, paso a paso, en una PWA completa. Escribiremos a mano el manifiesto, el service worker, la página sin conexión y las estrategias de caché, para entender qué ocurre por debajo. Después veremos cómo delegar el trabajo repetitivo en Workbox y en un plugin para Vite, cómo comprobar el resultado con Lighthouse y qué errores suelen aparecer en producción.

Los requisitos son modestos: conocer HTML y JavaScript, tener Node.js en una versión LTS actual y un navegador basado en Chromium para las herramientas de desarrollo. Si vienes de un proyecto con empaquetador, te vendrá bien revisar cómo se organiza una configuración inicial de proyectos front-end con Vite, porque en la segunda mitad del artículo usaremos ese ecosistema.

Antes de escribir código conviene fijar el modelo mental. Una PWA se apoya en cuatro piezas:

  • Un origen servido por HTTPS, que es lo que habilita las APIs sensibles del navegador.
  • Un manifiesto web, un archivo JSON que describe nombre, iconos, colores y modo de visualización.
  • Un service worker, un script que se ejecuta aparte de la página y actúa como intermediario entre la aplicación y la red.
  • Una interfaz adaptable, que funcione bien en pantallas pequeñas y grandes.

Lo “progresivo” del nombre significa que cada capacidad se añade por capas. Un navegador que no soporte service workers seguirá mostrando el sitio como cualquier página; uno moderno obtendrá instalación y funcionamiento sin conexión. Nadie queda excluido, y por eso la mejora progresiva es el principio de diseño que guía todo lo que sigue, porque la mejora progresiva por capas evita romper nada en navegadores antiguos.

Estructura inicial del proyecto

Partimos de una carpeta con el mínimo imprescindible. No hay empaquetador todavía: trabajaremos con archivos estáticos para ver cada mecanismo sin intermediarios.

marcapaginas/
├── index.html
├── offline.html
├── manifest.webmanifest
├── sw.js
├── css/
│   └── estilos.css
├── js/
│   └── app.js
└── iconos/
    ├── icono-192.png
    ├── icono-512.png
    └── icono-maskable-512.png

La página principal es deliberadamente simple. Tiene una lista de lecturas guardada en localStorage y un formulario para añadir títulos nuevos.

<!doctype html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Marcapáginas</title>
  <meta name="theme-color" content="#1f6f5c">
  <link rel="manifest" href="/manifest.webmanifest">
  <link rel="icon" href="/iconos/icono-192.png">
  <link rel="apple-touch-icon" href="/iconos/icono-192.png">
  <link rel="stylesheet" href="/css/estilos.css">
</head>
<body>
  <main>
    <h1>Marcapáginas</h1>
    <form id="form-lectura">
      <input id="titulo" placeholder="Título del libro" required>
      <button type="submit">Añadir</button>
    </form>
    <ul id="lista"></ul>
    <p id="estado-red" role="status"></p>
  </main>
  <script type="module" src="/js/app.js"></script>
</body>
</html>

Dos detalles merecen atención. La etiqueta meta viewport es obligatoria para que el diseño se adapte a móviles, y theme-color tiñe la barra del navegador con el color de la marca. El resto de las líneas importantes, el enlace al manifiesto, lo explicamos enseguida.

El código de la aplicación es corto y no depende de la red, lo que facilita demostrar el modo sin conexión.

const form = document.querySelector("#form-lectura");
const lista = document.querySelector("#lista");
const estado = document.querySelector("#estado-red");

const leer = () => JSON.parse(localStorage.getItem("lecturas") ?? "[]");
const guardar = (items) => localStorage.setItem("lecturas", JSON.stringify(items));

function pintar() {
  lista.replaceChildren(
    ...leer().map((titulo) => {
      const li = document.createElement("li");
      li.textContent = titulo;
      return li;
    })
  );
}

form.addEventListener("submit", (e) => {
  e.preventDefault();
  const input = document.querySelector("#titulo");
  guardar([...leer(), input.value.trim()]);
  input.value = "";
  pintar();
});

function actualizarEstado() {
  estado.textContent = navigator.onLine ? "" : "Sin conexión: trabajas en local";
}
window.addEventListener("online", actualizarEstado);
window.addEventListener("offline", actualizarEstado);

pintar();
actualizarEstado();

Para probar todo en local necesitas un servidor estático. Cualquiera sirve, y localhost cuenta como origen seguro, así que los service workers funcionan sin certificado durante el desarrollo.

npx serve .

El manifiesto web explicado campo a campo

El manifiesto es un archivo JSON que el navegador lee para saber cómo presentar la aplicación una vez instalada. Su extensión recomendada es .webmanifest y se enlaza desde el head con una etiqueta link de tipo manifest, como ya hicimos en la página principal.

{
  "name": "Marcapáginas: diario de lecturas",
  "short_name": "Marcapáginas",
  "description": "Anota y organiza tus lecturas, incluso sin conexión.",
  "id": "/",
  "start_url": "/?origen=pwa",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait-primary",
  "background_color": "#f6f1e7",
  "theme_color": "#1f6f5c",
  "lang": "es",
  "icons": [
    { "src": "/iconos/icono-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/iconos/icono-512.png", "sizes": "512x512", "type": "image/png" },
    {
      "src": "/iconos/icono-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "shortcuts": [
    {
      "name": "Añadir lectura",
      "url": "/?accion=nueva",
      "icons": [{ "src": "/iconos/icono-192.png", "sizes": "192x192" }]
    }
  ]
}

Repasemos los campos que más importan:

  • name y short_name: el primero aparece en el diálogo de instalación y el segundo bajo el icono, donde el espacio es escaso. Conviene que short_name no pase de doce caracteres aproximadamente.
  • id: identifica la aplicación de forma estable. Si más adelante cambias start_url, el navegador seguirá tratándola como la misma app gracias a este campo.
  • start_url: la dirección que se abre al lanzar la app instalada. Añadir un parámetro como origen=pwa permite distinguir en tus analíticas las sesiones instaladas de las del navegador.
  • scope: define qué rutas pertenecen a la aplicación. Navegar fuera de ese ámbito abre la barra del navegador.
  • display: standalone oculta la interfaz del navegador y es el modo habitual. Existen también minimal-ui, fullscreen y browser.
  • background_color: se usa en la pantalla de arranque mientras carga la interfaz.
  • icons: el conjunto mínimo para instalar en Chromium son los tamaños 192 y 512 píxeles.
  • shortcuts: accesos directos que aparecen al mantener pulsado el icono.

Iconos maskable

Android recorta los iconos con la forma que decida el fabricante: círculo, cuadrado redondeado, gota. Un icono marcado con purpose igual a maskable debe tener el motivo importante dentro de una “zona segura” central, aproximadamente el 80 % del lienzo, y el fondo a sangre hasta los bordes. Si solo declaras un icono normal, el sistema lo encaja dentro de un círculo blanco y queda poco profesional. Declara siempre una variante maskable y otra de propósito any por separado en lugar de combinarlas en un único icono.

Validar el manifiesto

Abre las herramientas de desarrollo, ve al panel Application y entra en Manifest. Allí verás los campos interpretados, los iconos renderizados y los avisos de lo que falta. Es la forma más rápida de detectar una ruta de icono equivocada o un start_url fuera del ámbito.

Primer service worker: registro y ciclo de vida

Un service worker es un archivo JavaScript que el navegador ejecuta en un hilo independiente, sin acceso al DOM. Su poder viene de que puede interceptar cada petición de red que hacen las páginas de su ámbito y decidir cómo responderla: desde la red, desde una caché local o con una respuesta fabricada.

El registro se hace desde la página y debe comprobar antes que el navegador lo soporte, siguiendo la mejora progresiva.

// js/registro-sw.js
export async function registrarServiceWorker() {
  if (!("serviceWorker" in navigator)) return;

  try {
    const registro = await navigator.serviceWorker.register("/sw.js", {
      scope: "/",
    });
    console.log("Service worker registrado en", registro.scope);
  } catch (error) {
    console.error("No se pudo registrar el service worker", error);
  }
}

Impórtalo desde app.js con una llamada al final y listo. El archivo sw.js debe vivir en la raíz si quieres que controle todo el sitio, porque el ámbito máximo de un worker es la carpeta donde está alojado.

Las tres fases

El ciclo de vida es la parte que más confunde al principio, así que conviene entenderlo bien:

  1. Instalación (install): ocurre una vez por versión del script. Es el momento ideal para precargar los archivos esenciales en la caché.
  2. Activación (activate): se dispara cuando el worker nuevo toma el control. Sirve para limpiar cachés antiguas.
  3. Funcionamiento (fetch y otros eventos): a partir de aquí el worker intercepta peticiones.

Hay una regla que provoca muchas dudas: un worker recién instalado queda en espera mientras exista otro worker anterior controlando pestañas abiertas. Solo se activa cuando se cierran todas esas pestañas, salvo que fuerces el relevo con skipWaiting() y clients.claim(). Más adelante veremos cuándo es sensato hacerlo y cuándo no.

Mientras desarrollas, activa en el panel Application, sección Service Workers, la casilla “Update on reload”. Evita la frustración de editar sw.js y seguir viendo la versión antigua.

Precarga del shell y página sin conexión

La interfaz mínima que necesita la aplicación para pintarse se suele llamar application shell: el HTML base, la hoja de estilos, el JavaScript principal y los iconos. Si todo eso está en caché, la app abre al instante aunque no haya red disponible en ese momento.

Empezamos por la página de respaldo. Debe ser autocontenida: estilos incrustados y ninguna dependencia externa, porque se mostrará justo cuando nada más esté disponible.

<!doctype html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Sin conexión · Marcapáginas</title>
  <style>
    body { font-family: system-ui, sans-serif; display: grid; place-items: center;
           min-height: 100vh; margin: 0; background: #f6f1e7; color: #222; }
    main { max-width: 28rem; padding: 1.5rem; text-align: center; }
    button { padding: .6rem 1.2rem; font-size: 1rem; }
  </style>
</head>
<body>
  <main>
    <h1>Estás sin conexión</h1>
    <p>Esta sección necesita internet. Tus lecturas guardadas siguen disponibles en la pantalla principal.</p>
    <button onclick="location.reload()">Reintentar</button>
  </main>
</body>
</html>

Ahora el service worker. Versionamos el nombre de la caché para poder invalidarla al publicar cambios.

// sw.js
const VERSION = "v1";
const CACHE_SHELL = `marcapaginas-shell-${VERSION}`;

const ARCHIVOS_SHELL = [
  "/",
  "/index.html",
  "/offline.html",
  "/css/estilos.css",
  "/js/app.js",
  "/js/registro-sw.js",
  "/iconos/icono-192.png",
  "/iconos/icono-512.png",
];

self.addEventListener("install", (evento) => {
  evento.waitUntil(
    caches.open(CACHE_SHELL).then((cache) => cache.addAll(ARCHIVOS_SHELL))
  );
});

self.addEventListener("activate", (evento) => {
  evento.waitUntil(
    caches.keys().then((nombres) =>
      Promise.all(
        nombres
          .filter((n) => n.startsWith("marcapaginas-") && n !== CACHE_SHELL)
          .map((n) => caches.delete(n))
      )
    )
  );
});

waitUntil le dice al navegador que no considere terminada la fase hasta que la promesa se resuelva. Sin él, el worker podría ser descartado a mitad de la descarga. Además, addAll es atómico: si un solo archivo falla, falla toda la instalación y el worker no se activa. Es un comportamiento útil, porque evita quedarse con un shell incompleto, pero obliga a revisar bien las rutas.

Responder con la caché y caer a la página offline

Añadimos el manejador fetch. Para las navegaciones, intentamos la red y, si falla, entregamos la página de respaldo. Para el resto de peticiones, servimos desde la caché cuando exista.

self.addEventListener("fetch", (evento) => {
  const peticion = evento.request;

  if (peticion.method !== "GET") return;

  if (peticion.mode === "navigate") {
    evento.respondWith(
      fetch(peticion).catch(async () => {
        const cache = await caches.open(CACHE_SHELL);
        return (await cache.match(peticion)) ?? cache.match("/offline.html");
      })
    );
    return;
  }

  evento.respondWith(
    caches.match(peticion).then((guardada) => guardada ?? fetch(peticion))
  );
});

Observa el primer return: solo gestionamos peticiones GET, porque las demás tienen efectos secundarios y no deben cachearse. Para comprobar el resultado, carga la página, abre el panel Network, marca “Offline” y recarga. Deberías ver la aplicación funcionando y, al navegar a una ruta inexistente en la caché, la página de respaldo.

Estrategias de caché: elegir según el tipo de recurso

No todos los recursos merecen el mismo trato. Un logotipo casi nunca cambia, mientras que la respuesta de una API de precios caduca en minutos. Las estrategias clásicas se pueden implementar con unas pocas líneas cada una.

Cache first

Primero la caché y, si no hay copia, la red. Es ideal para recursos versionados e inmutables, como los archivos con hash en el nombre, fuentes o imágenes.

async function cachePrimero(peticion, nombreCache) {
  const cache = await caches.open(nombreCache);
  const guardada = await cache.match(peticion);
  if (guardada) return guardada;

  const respuesta = await fetch(peticion);
  if (respuesta.ok) cache.put(peticion, respuesta.clone());
  return respuesta;
}

El clone() es imprescindible: el cuerpo de una respuesta solo se puede leer una vez, así que una copia va a la caché y la original al navegador.

Network first

Primero la red, con la caché como red de seguridad. Conviene para datos que deben estar frescos pero que preferimos tener obsoletos antes que no tener nada, como el listado de recomendaciones.

async function redPrimero(peticion, nombreCache, esperaMs = 3000) {
  const cache = await caches.open(nombreCache);
  try {
    const controlador = new AbortController();
    const temporizador = setTimeout(() => controlador.abort(), esperaMs);
    const respuesta = await fetch(peticion, { signal: controlador.signal });
    clearTimeout(temporizador);
    if (respuesta.ok) cache.put(peticion, respuesta.clone());
    return respuesta;
  } catch {
    const guardada = await cache.match(peticion);
    if (guardada) return guardada;
    throw new Error("Sin red y sin copia en caché");
  }
}

El temporizador evita que una red muy lenta deje al usuario esperando indefinidamente. Si en tres segundos no hay respuesta, se usa la copia.

Stale while revalidate

Devuelve de inmediato lo que haya en caché y, en paralelo, pide una versión nueva para la próxima visita. Ofrece la rapidez de cache first con una frescura razonable, y es una buena opción por defecto para hojas de estilos, scripts sin hash y datos de poca criticidad.

async function obsoletoYRevalida(evento, nombreCache) {
  const cache = await caches.open(nombreCache);
  const guardada = await cache.match(evento.request);

  const actualizacion = fetch(evento.request)
    .then((respuesta) => {
      if (respuesta.ok) cache.put(evento.request, respuesta.clone());
      return respuesta;
    })
    .catch(() => guardada);

  evento.waitUntil(actualizacion);
  return guardada ?? actualizacion;
}

Aquí waitUntil mantiene vivo el worker hasta que termine la actualización en segundo plano, aunque la respuesta ya se haya entregado.

Solo red y solo caché

Existen dos extremos. “Solo red” se aplica a peticiones que nunca deben guardarse, como un pago o una autenticación. “Solo caché” sirve únicamente para recursos que sabes que se precargaron en la instalación. En la práctica se usan poco, pero es útil conocerlos para razonar con precisión.

Cómo enrutar cada estrategia

Con las funciones anteriores, el manejador fetch pasa a ser un pequeño enrutador que decide por tipo de petición.

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

  if (request.method !== "GET" || url.origin !== self.location.origin) return;

  if (request.mode === "navigate") {
    evento.respondWith(navegacionConRespaldo(request));
  } else if (url.pathname.startsWith("/api/")) {
    evento.respondWith(redPrimero(request, "marcapaginas-api"));
  } else if (/\.(?:png|jpg|webp|svg|woff2)$/.test(url.pathname)) {
    evento.respondWith(cachePrimero(request, "marcapaginas-medios"));
  } else {
    evento.respondWith(obsoletoYRevalida(evento, "marcapaginas-estaticos"));
  }
});

Una pauta práctica para decidir: lo que pesa y no cambia, cache first; lo que cambia pero tolera un poco de retraso, stale while revalidate; lo que debe ser correcto o nada, network first con respaldo o solo red. Si te interesa cuantificar el impacto de estas decisiones en la carga inicial, la guía de fuentes web rápidas y rendimiento de carga complementa bien este punto, sobre todo para las tipografías.

Actualizaciones del service worker sin sorpresas

El mayor problema de producción con los service workers no es técnico, sino de experiencia: un usuario puede quedarse con una versión antigua durante días. El navegador comprueba si sw.js cambió, byte a byte, cuando se navega a una página del ámbito y como mucho una vez cada 24 horas. Si hay diferencias, instala el nuevo worker en segundo plano, pero lo deja en espera.

La salida más simple es llamar a skipWaiting() durante la instalación. Funciona, pero tiene un riesgo real: la página abierta puede haber cargado un JavaScript de la versión antigua y recibir de pronto recursos de la nueva, con nombres de archivo distintos. El resultado son errores difíciles de reproducir.

Una alternativa más cuidadosa es avisar al usuario y dejarle decidir cuándo recargar.

// js/registro-sw.js (versión con aviso de actualización)
export async function registrarServiceWorker(alHaberNovedad) {
  if (!("serviceWorker" in navigator)) return;

  const registro = await navigator.serviceWorker.register("/sw.js");

  registro.addEventListener("updatefound", () => {
    const nuevo = registro.installing;
    nuevo?.addEventListener("statechange", () => {
      if (nuevo.state === "installed" && navigator.serviceWorker.controller) {
        alHaberNovedad(() => nuevo.postMessage({ tipo: "ACTIVAR_YA" }));
      }
    });
  });

  let recargando = false;
  navigator.serviceWorker.addEventListener("controllerchange", () => {
    if (recargando) return;
    recargando = true;
    location.reload();
  });
}

Y en el worker, escuchamos el mensaje para relevar al anterior solo cuando el usuario lo pida.

self.addEventListener("message", (evento) => {
  if (evento.data?.tipo === "ACTIVAR_YA") self.skipWaiting();
});

En la interfaz mostrarías un aviso discreto del estilo “Hay una versión nueva” con un botón que ejecute la función recibida. El indicador recargando evita un bucle de recargas cuando el controlador cambia. Si además el usuario pierde datos de formulario al recargar, conviene guardar el borrador antes.

Una norma de oro: para que el navegador detecte versiones nuevas, sirve siempre sw.js con una cabecera Cache-Control igual a no-cache, o con una caducidad muy corta. Si el propio worker queda atrapado en la caché HTTP del navegador, nunca se enterará de que existe una versión nueva.

Instalación: criterios, evento y botón propio

Para que Chromium ofrezca la instalación, la aplicación debe servirse por HTTPS, enlazar un manifiesto válido con nombre, iconos de 192 y 512 píxeles, start_url y un display distinto de browser. Hoy ya no es obligatorio tener un manejador fetch para instalar en la mayoría de escenarios de escritorio y Android, aunque sin él no hay funcionamiento sin conexión, que es la razón de ser de la mayor parte de las PWA.

En Chromium se dispara el evento beforeinstallprompt cuando se cumplen los criterios. Lo podemos capturar para ofrecer un botón propio, en un momento oportuno del flujo del usuario en lugar de un aviso genérico.

let solicitudInstalacion = null;
const botonInstalar = document.querySelector("#instalar");
botonInstalar.hidden = true;

window.addEventListener("beforeinstallprompt", (evento) => {
  evento.preventDefault();
  solicitudInstalacion = evento;
  botonInstalar.hidden = false;
});

botonInstalar.addEventListener("click", async () => {
  if (!solicitudInstalacion) return;
  solicitudInstalacion.prompt();
  const { outcome } = await solicitudInstalacion.userChoice;
  console.log("Resultado de la instalación:", outcome);
  solicitudInstalacion = null;
  botonInstalar.hidden = true;
});

window.addEventListener("appinstalled", () => {
  console.log("Aplicación instalada");
});

Hay matices de compatibilidad. Este evento no existe en Safari ni en Firefox de escritorio: en iOS y iPadOS la instalación se hace desde el menú Compartir con la opción “Añadir a pantalla de inicio”, y no puedes lanzar el diálogo por código. Por eso el botón debe estar oculto por defecto y aparecer solo cuando el navegador lo permita. Si quieres orientar a usuarios de iOS, detecta la plataforma y muestra una pequeña indicación textual con los pasos.

Detectar si la app ya está instalada

Para adaptar la interfaz, por ejemplo ocultando enlaces de descarga, usa una consulta de medios.

const esInstalada = window.matchMedia("(display-mode: standalone)").matches;
if (esInstalada) document.body.classList.add("modo-app");

En CSS puedes aplicar reglas específicas con la misma consulta, útil para ajustar márgenes cuando desaparece la barra de direcciones.

@media (display-mode: standalone) {
  header { padding-top: env(safe-area-inset-top); }
  .enlace-descarga { display: none; }
}

HTTPS: requisito y cómo trabajar en local

Los service workers solo se registran en contextos seguros porque tienen poder para interceptar y alterar respuestas. Un atacante que pudiera inyectar uno en una conexión sin cifrar tendría control persistente sobre el sitio. Por eso producción exige HTTPS sin excepciones, y esa exigencia se aplica también a muchas otras APIs, como geolocalización, notificaciones push o el portapapeles.

Para desarrollo tienes tres situaciones:

  • localhost se trata como origen seguro y no necesita certificado.
  • Para probar desde el móvil con la IP de tu red local, necesitas un certificado de confianza. Herramientas como mkcert crean una autoridad local y certificados firmados por ella.
  • Para compartir un prototipo, un túnel con certificado válido evita configurar nada.
mkcert -install
mkcert -key-file clave.pem -cert-file certificado.pem localhost 192.168.1.40
npx serve . --ssl-cert certificado.pem --ssl-key clave.pem

En producción, los proveedores de hosting estático y las redes de entrega de contenido emiten y renuévan certificados automáticamente. Si gestionas tu propio servidor, una autoridad gratuita con renovación automática es suficiente. Comprueba además que la redirección de HTTP a HTTPS sea permanente y que el manifiesto, el worker y los iconos se sirvan con el tipo MIME correcto: application/manifest+json o application/json para el manifiesto y text/javascript para el worker. Para entender qué pasa entre el navegador y el servidor en una conexión cifrada, repasa el viaje completo de una petición web, donde se detallan DNS, TLS y cabeceras.

Dejar el trabajo repetitivo a Workbox

Escribir a mano el enrutador y las estrategias enseña mucho, pero en un proyecto real mantener listas de archivos, versiones y reglas de caducidad es propenso a errores. Workbox es la biblioteca de referencia para esto: ofrece módulos para precarga, enrutamiento y estrategias ya probadas. La serie estable actual es la 7.x, y los módulos se instalan por separado.

npm install --save-dev workbox-build
npm install workbox-core workbox-precaching workbox-routing workbox-strategies workbox-expiration workbox-cacheable-response

Escribimos un worker de origen, sw-origen.js, que solo describe las reglas. Los marcadores de precarga los rellenará la herramienta de compilación.

// sw-origen.js
import { precacheAndRoute, cleanupOutdatedCaches, matchPrecache } from "workbox-precaching";
import { registerRoute, setCatchHandler, NavigationRoute } from "workbox-routing";
import { CacheFirst, StaleWhileRevalidate, NetworkFirst } from "workbox-strategies";
import { ExpirationPlugin } from "workbox-expiration";
import { CacheableResponsePlugin } from "workbox-cacheable-response";

cleanupOutdatedCaches();
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({ request }) => request.destination === "image",
  new CacheFirst({
    cacheName: "imagenes",
    plugins: [
      new CacheableResponsePlugin({ statuses: [0, 200] }),
      new ExpirationPlugin({ maxEntries: 60, maxAgeSeconds: 60 * 60 * 24 * 30 }),
    ],
  })
);

registerRoute(
  ({ url }) => url.pathname.startsWith("/api/"),
  new NetworkFirst({ cacheName: "api", networkTimeoutSeconds: 3 })
);

registerRoute(
  ({ request }) => ["style", "script", "font"].includes(request.destination),
  new StaleWhileRevalidate({ cacheName: "recursos" })
);

setCatchHandler(async ({ request }) => {
  if (request.destination === "document") {
    return matchPrecache("/offline.html");
  }
  return Response.error();
});

self.addEventListener("message", (e) => {
  if (e.data?.tipo === "ACTIVAR_YA") self.skipWaiting();
});

Las ventajas son concretas: ExpirationPlugin limita el tamaño y la antigüedad de cada caché, algo que a mano exige bastante código; CacheableResponsePlugin permite guardar respuestas opacas con estado cero, típicas de recursos de otros orígenes; y cleanupOutdatedCaches elimina precachés de versiones anteriores.

Luego un script de compilación con injectManifest genera el worker final, sustituyendo self.__WB_MANIFEST por la lista de archivos con su hash de contenido.

// construir-sw.mjs
import { injectManifest } from "workbox-build";

const { count, size, warnings } = await injectManifest({
  swSrc: "sw-origen.js",
  swDest: "dist/sw.js",
  globDirectory: "dist",
  globPatterns: ["**/*.{html,js,css,png,webp,svg,woff2,webmanifest}"],
});

warnings.forEach(console.warn);
console.log(`Precacheados ${count} archivos (${(size / 1024).toFixed(1)} KiB)`);
Precacheados 14 archivos (212.6 KiB)

Como el nombre de cada archivo precacheado lleva una revisión calculada del contenido, cuando cambias uno solo el navegador descarga únicamente ese, no todo el shell. Esa es la diferencia esencial frente a nuestro VERSION = "v1" manual, que invalida todo a la vez.

PWA con Vite y vite-plugin-pwa

Si ya trabajas con Vite, no necesitas montar el script anterior: vite-plugin-pwa integra Workbox en la compilación, genera el manifiesto y el worker y se encarga del registro. La serie 1.x del plugin es la vigente y requiere una versión de Node compatible con la de Vite que uses; comprueba en la documentación del plugin su rango de compatibilidad antes de actualizar.

npm create vite@latest marcapaginas-vite -- --template vanilla
cd marcapaginas-vite
npm install
npm install --save-dev vite-plugin-pwa

La configuración queda reunida en un único archivo.

// vite.config.js
import { defineConfig } from "vite";
import { VitePWA } from "vite-plugin-pwa";

export default defineConfig({
  plugins: [
    VitePWA({
      registerType: "prompt",
      includeAssets: ["offline.html", "iconos/*.png"],
      manifest: {
        name: "Marcapáginas: diario de lecturas",
        short_name: "Marcapáginas",
        start_url: "/",
        display: "standalone",
        background_color: "#f6f1e7",
        theme_color: "#1f6f5c",
        icons: [
          { src: "iconos/icono-192.png", sizes: "192x192", type: "image/png" },
          { src: "iconos/icono-512.png", sizes: "512x512", type: "image/png" },
          {
            src: "iconos/icono-maskable-512.png",
            sizes: "512x512",
            type: "image/png",
            purpose: "maskable",
          },
        ],
      },
      workbox: {
        navigateFallback: "/offline.html",
        runtimeCaching: [
          {
            urlPattern: ({ url }) => url.pathname.startsWith("/api/"),
            handler: "NetworkFirst",
            options: { cacheName: "api", networkTimeoutSeconds: 3 },
          },
        ],
      },
      devOptions: { enabled: true },
    }),
  ],
});

Con registerType igual a prompt, la actualización queda a decisión del usuario, y con autoUpdate se aplica sola. Para el aviso se importa un módulo virtual que expone el registro.

import { registerSW } from "virtual:pwa-register";

const actualizar = registerSW({
  onNeedRefresh() {
    if (confirm("Hay una versión nueva. ¿Recargar ahora?")) actualizar(true);
  },
  onOfflineReady() {
    console.log("Lista para usarse sin conexión");
  },
});

Ten en cuenta que navigateFallback con la página offline sirve esa página a cualquier navegación sin copia, lo cual en una aplicación de una sola página suele ser indeseable: lo habitual es apuntar a index.html para que el enrutador del cliente resuelva la ruta. Usa la página offline como último recurso con un manejador de captura, como hicimos con Workbox a mano, cuando tengas varias páginas reales.

La opción devOptions activa el worker durante npm run dev, útil para depurar, pero recuerda que en desarrollo los archivos no llevan hash y los resultados no representan la producción. Para validar el comportamiento real compila y sirve el resultado.

npm run build
npm run preview

Auditoría con Lighthouse y depuración

Lighthouse viene integrado en las herramientas de desarrollo de Chromium, en el panel del mismo nombre, y también existe como paquete de línea de comandos. Mide rendimiento, accesibilidad, buenas prácticas y SEO, y ofrece comprobaciones específicas de instalabilidad. Conviene lanzarlo siempre contra la versión compilada y servida por HTTPS, en una ventana de incógnito para que las extensiones no distorsionen la medición.

npm install --global lighthouse
lighthouse https://tu-dominio.example --only-categories=performance,accessibility,best-practices,seo --view

Un informe sin problemas de instalabilidad indica que el navegador reconoce la aplicación como instalable. Si aparecen avisos, los más frecuentes son iconos ausentes en 512 píxeles, start_url que devuelve un error al estar sin conexión, falta de la etiqueta viewport y un color de tema no declarado. Por otra parte, el panel Application ofrece comprobaciones útiles que Lighthouse no cubre:

  • Service Workers: estado, errores de registro, botones para forzar actualización, simular sin conexión y lanzar eventos push o sync de prueba.
  • Cache Storage: contenido de cada caché, con la posibilidad de borrar entradas sueltas.
  • Storage: cuota usada y botón para limpiar datos del sitio, imprescindible cuando quieres volver a un estado limpio.

Una buena práctica es incluir Lighthouse en la integración continua con un umbral mínimo de puntuación, de modo que una regresión de rendimiento o de accesibilidad bloquee la fusión de cambios. Al ser puntuaciones que varían ligeramente entre ejecuciones, lanza varias y usa la mediana.

Datos locales y sincronización básica

Una aplicación sin conexión que no guarda datos es solo una carcasa. Para volúmenes pequeños basta localStorage, como en Marcapáginas, pero tiene límites: es síncrono, solo guarda cadenas y no está disponible dentro del service worker. Para datos estructurados o mayores, la opción es IndexedDB, con una envoltura ligera que evite su API de eventos.

const abrir = () =>
  new Promise((resolve, reject) => {
    const peticion = indexedDB.open("marcapaginas", 1);
    peticion.onupgradeneeded = () =>
      peticion.result.createObjectStore("pendientes", { autoIncrement: true });
    peticion.onsuccess = () => resolve(peticion.result);
    peticion.onerror = () => reject(peticion.error);
  });

export async function encolar(lectura) {
  const db = await abrir();
  return new Promise((resolve, reject) => {
    const tx = db.transaction("pendientes", "readwrite");
    tx.objectStore("pendientes").add(lectura);
    tx.oncomplete = resolve;
    tx.onerror = () => reject(tx.error);
  });
}

El patrón de cola de pendientes consiste en guardar localmente las acciones realizadas sin conexión y enviarlas cuando vuelva la red. La API de sincronización en segundo plano permite que el navegador lo haga incluso con la pestaña cerrada, pero su soporte está limitado a navegadores basados en Chromium. Por eso la versión robusta combina ambas vías: registra un sync cuando existe y, como respaldo, vacía la cola al oír el evento online.

// En la página
async function pedirSincronizacion() {
  const registro = await navigator.serviceWorker.ready;
  if ("sync" in registro) {
    await registro.sync.register("enviar-pendientes");
  } else {
    window.addEventListener("online", vaciarCola, { once: true });
  }
}

// En sw.js
self.addEventListener("sync", (evento) => {
  if (evento.tag === "enviar-pendientes") evento.waitUntil(vaciarCola());
});

Piensa también en los conflictos: si dos dispositivos editan lo mismo sin conexión, el servidor debe decidir qué versión gana. Una estrategia sencilla es el último cambio por marca de tiempo; otras aplicaciones necesitan fusionar campo a campo. Diseña esto desde el principio, porque es mucho más difícil añadirlo después.

Errores comunes y cómo solucionarlos

Después de montar varias PWA, estos son los tropiezos que más se repiten:

  • Cachear respuestas de error. Guardar una respuesta 404 o 500 y servirla después como si fuera válida es muy común. Comprueba siempre respuesta.ok antes de llamar a put, salvo en recursos de otros orígenes donde la respuesta opaca tiene estado cero.
  • Cachear el HTML con una estrategia de cache first. La página principal queda congelada y los usuarios nunca ven los despliegues nuevos. El HTML de navegación debe ir con network first o con precarga versionada.
  • Olvidar el ámbito. Un worker en una subcarpeta solo controla esa subcarpeta. Si necesitas ampliarlo, el servidor debe enviar la cabecera Service-Worker-Allowed.
  • No limpiar cachés antiguas. Cada versión crea cachés nuevas y las viejas siguen ocupando espacio hasta que el navegador las expulsa por cuota. Elimínalas en activate.
  • Cachear rutas con datos privados. Si una respuesta contiene información de la sesión de un usuario y el dispositivo es compartido, la siguiente persona podría verla. Excluye de la caché los endpoints autenticados o límpiala al cerrar sesión.
  • Confiar en navigator.onLine. Un valor verdadero solo indica que hay una interfaz de red, no que haya acceso a internet. La única prueba fiable es intentar la petición y gestionar el fallo.
  • Probar solo con la caché caliente. Todo funciona en tu máquina porque ya has cargado la página diez veces. Borra el almacenamiento del sitio y repite el flujo de primera visita y de segunda visita sin conexión.
  • Iconos con fondo transparente en la variante maskable. El sistema rellena con negro y el resultado es poco legible. Usa un fondo sólido.
  • Redirecciones en recursos precacheados. Los navegadores rechazan por defecto respuestas redirigidas para peticiones de navegación servidas desde el worker. Precachea la dirección final, no la que redirige.

Cuando algo no se actualiza

Sigue un orden fijo de comprobación. Primero, en Application, mira si hay un worker en espera. Segundo, revisa en Network que sw.js se pidió de nuevo y con qué cabeceras de caché. Tercero, mira en Cache Storage si el nombre de la caché cambió con la versión. Por último, en un dispositivo concreto, usa el botón “Unregister” y “Clear site data” para volver a un estado conocido. Cuando una publicación con un fallo grave deja usuarios atrapados, la salida de emergencia es desplegar un sw.js que se desregistre y limpie las cachés.

// sw.js de emergencia: se desregistra y limpia todo
self.addEventListener("install", () => self.skipWaiting());
self.addEventListener("activate", (evento) => {
  evento.waitUntil(
    (async () => {
      const nombres = await caches.keys();
      await Promise.all(nombres.map((n) => caches.delete(n)));
      await self.registration.unregister();
      const clientes = await self.clients.matchAll({ type: "window" });
      clientes.forEach((c) => c.navigate(c.url));
    })()
  );
});

Buenas prácticas de rendimiento y seguridad

La caché del service worker no sustituye una buena base de rendimiento; la amplifica. Reduce lo que se descarga antes de cachearlo, con imágenes en formatos modernos, tipografías con subconjuntos y JavaScript dividido por rutas. Precachea solo el shell realmente necesario: una precarga de varios megabytes en la primera visita penaliza a quien tiene una conexión lenta y consume su cuota de datos.

Respecto a la seguridad, aplica estas pautas:

  1. Sirve todo por HTTPS y añade la cabecera Strict-Transport-Security una vez estés seguro de que no habrá regresiones.
  2. Define una política de seguridad de contenido restrictiva. Un script malicioso inyectado en la página puede registrar un worker propio, así que cierra la puerta a la inyección en primer lugar.
  3. No cachees respuestas con cabeceras Cache-Control igual a no-store ni datos sensibles; respeta la intención del servidor.
  4. Limita el tamaño de las cachés dinámicas con caducidad por número de entradas y por edad.
  5. Si usas notificaciones push, pide el permiso en respuesta a una acción explícita del usuario y no al cargar la página; los navegadores penalizan y bloquean a los sitios que lo piden de forma intrusiva.

Sobre la cuota de almacenamiento, puedes consultarla desde JavaScript y pedir que el navegador trate tus datos como persistentes para que no los borre ante falta de espacio.

if (navigator.storage?.estimate) {
  const { usage, quota } = await navigator.storage.estimate();
  console.log(`Usado ${(usage / 1048576).toFixed(1)} MiB de ${(quota / 1048576).toFixed(0)} MiB`);
}
if (navigator.storage?.persist) {
  const concedido = await navigator.storage.persist();
  console.log("Almacenamiento persistente:", concedido);
}

Cuándo elegir una PWA frente a otras opciones

Una PWA no siempre es la mejor respuesta. Es muy adecuada para herramientas de productividad, tiendas, paneles internos, lectores y aplicaciones centradas en contenido, donde una sola base de código y un despliegue instantáneo son una ventaja enorme. Además, al ser indexable por buscadores, hereda las ventajas del SEO de la web, algo imposible en una aplicación de tienda.

Conviene valorar alternativas cuando necesitas acceso profundo al hardware, como Bluetooth avanzado, sensores específicos, procesamiento en segundo plano continuo o integración estrecha con el sistema operativo. Las aplicaciones híbridas con un contenedor nativo cubren parte de ese hueco, y el desarrollo totalmente nativo sigue siendo la opción para juegos exigentes o aplicaciones de gran carga gráfica. Hay también diferencias de plataforma: en iOS, las PWA instaladas han ido ganando capacidades, pero las notificaciones push y algunas APIs tienen condiciones propias, por lo que es prudente probar en dispositivos reales y consultar la tabla de compatibilidad actual antes de prometer una función a un cliente.

Un criterio práctico de decisión: si el 90 % de tu valor es mostrar y editar datos con una buena experiencia móvil, empieza con una PWA. Si descubres un bloqueo concreto de la plataforma, entonces evalúa envolverla en un contenedor nativo en lugar de reescribirla.

Lista de comprobación antes de publicar

Antes de poner la aplicación en manos de usuarios, repasa estos puntos en orden:

  1. El sitio se sirve solo por HTTPS y HTTP redirige de forma permanente.
  2. El manifiesto es válido, con id, name, short_name, start_url, scope, display, colores e iconos de 192, 512 y maskable.
  3. El head incluye viewport, theme-color y el enlace al manifiesto.
  4. El service worker se sirve con una caché HTTP corta o inexistente y su ámbito es el correcto.
  5. Existe una página sin conexión autocontenida y se entrega cuando falla la navegación.
  6. Cada tipo de recurso tiene una estrategia deliberada, y las respuestas no válidas no se guardan.
  7. Las cachés antiguas se eliminan al activar una nueva versión y hay un flujo claro de actualización.
  8. Lighthouse no reporta problemas de instalabilidad y las puntuaciones superan el umbral que te hayas marcado.
  9. Has probado primera visita, segunda visita sin conexión, actualización y desinstalación en al menos un móvil Android, un iPhone y un navegador de escritorio.
  10. Tienes un plan de emergencia para retirar un worker defectuoso.

Conclusiones

Convertir un sitio en una PWA es una suma de piezas pequeñas que se entienden bien por separado: un manifiesto que describe la aplicación, un service worker que gobierna la red, una página de respaldo, estrategias de caché adaptadas a cada recurso y HTTPS como cimiento. Escribirlas a mano una vez, como hicimos con Marcapáginas, te da el criterio para depurar cualquier problema posterior, aunque en un proyecto real lo normal sea apoyarte en Workbox o en el plugin de Vite para mantener las listas de archivos y las revisiones sin errores.

Lo más importante no es el código, sino las decisiones de diseño. Elige estrategias con intención, cuida el flujo de actualización para no dejar a nadie atrapado en una versión vieja, no guardes datos que no deban persistir y verifica el resultado en dispositivos reales y con Lighthouse. Aplica siempre la mejora progresiva: la aplicación debe seguir siendo útil donde las capacidades no existan y sorprender donde sí lo hacen.

Como siguiente paso, prueba a añadir notificaciones push, accesos directos con más acciones o una cola de sincronización con resolución de conflictos. Cada una de ellas se apoya en la misma base que ya has construido.