Las trampas de hacer una PWA de verdad instalable
"Agrega un manifest.json y ya es una PWA" es una idea a medias. Con un manifest y HTTPS el navegador suele ofrecer instalar, pero instalada no significa bien instalada: la app que se queda atrás cuando publicas una versión nueva, la cabecera que tapa la isla dinámica del iPhone o el icono recortado en círculo son fallos que no aparecen en la primera prueba de escritorio. Aparecen al segundo o tercer día de uso en un teléfono real.
Esta nota reúne lo que nos pasó al volver instalables varios sistemas propios, como un panel de monitoreo, una plataforma de mensajería y una app de estudio. Primero va lo que el navegador exige de verdad, luego las trampas con su síntoma exacto y al final cómo probarlo. Las notificaciones push, que dependen de todo esto, tienen su propia nota: Push en iPhone sin app nativa.
Qué exige el navegador para ofrecer la instalación
Según la guía de web.dev sobre criterios de instalación, Chrome pide lo siguiente antes de lanzar el aviso de instalación:
- Servir la página por HTTPS.
- Un manifest con
nameoshort_name,start_urleiconsque incluyan uno de 192 px y otro de 512 px. displayenfullscreen,standalone,minimal-uiowindow-controls-overlay.prefer_related_applicationsausente o enfalse.- Que la persona haya hecho clic o toque en la página y la haya visto al menos 30 segundos.
Fíjate en lo que no aparece en esa lista: un service worker. Las guías antiguas lo daban como requisito y todavía circula esa idea. Hoy la lista oficial de Chrome no lo menciona. Aun así, nosotros registramos siempre uno, aunque sea mínimo, por tres razones: sin él no hay modo sin conexión, sin él no hay Web Push y es la pieza que nos permite controlar cómo se actualiza la app. Si tu sitio solo necesita un acceso directo, el manifest basta. Si quieres que se comporte como app, necesitas el service worker.
En iPhone el camino es otro. WebKit explica en su
anuncio de iOS 16.4
que un sitio con manifest y display en standalone
o fullscreen se agrega desde el menú Compartir como app de
pantalla de inicio. Sin manifest ni la etiqueta de app web, queda como un
simple marcador que abre Safari. No existe un aviso automático de
instalación como el de Chrome: la persona tiene que saber que debe usar
Compartir y luego Agregar a inicio, así que conviene explicárselo en la
propia pantalla.
Un manifest mínimo que funciona
{
"name": "Panel de monitoreo",
"short_name": "Monitoreo",
"start_url": "/?origen=pwa",
"scope": "/",
"display": "standalone",
"background_color": "#0b0b0c",
"theme_color": "#0b0b0c",
"icons": [
{ "src": "/icons/192.png", "sizes": "192x192", "type": "image/png" },
{ "src": "/icons/512.png", "sizes": "512x512", "type": "image/png" },
{ "src": "/icons/maskable-512.png", "sizes": "512x512",
"type": "image/png", "purpose": "maskable" }
]
}
Dos detalles prácticos. El parámetro ?origen=pwa en
start_url te deja medir cuántas aperturas vienen del icono
instalado. Y el icono maskable va como entrada propia: según
MDN,
ese purpose indica que el diseño ya contempla una máscara y
que todo lo que quede fuera de la zona segura puede recortarse. En Android
el recorte suele ser circular, por eso el maskable necesita más margen
alrededor del dibujo que el icono normal. Si usas un solo icono con logo
pegado a los bordes para ambos fines, lo verás cortado.
Los PNG se pueden generar sin librerías externas: en Node basta armar los
bloques IHDR, IDAT e IEND y comprimir los píxeles con
zlib.deflateSync. Otra opción es renderizar un HTML con un
navegador sin interfaz y capturarlo. Para iOS, recuerda que el
apple-touch-icon declarado en el head tiene
prioridad sobre los iconos del manifest, según el mismo artículo de WebKit.
Trampa 1: el service worker que se queda congelado
Síntoma: publicas una versión nueva y quien ya instaló la app sigue viendo la anterior durante días. No hay error en consola.
El caso típico: el servidor estático de Express llevaba
maxAge: '1y' con immutable sobre toda la carpeta
de salida. Esa caché de un año alcanzaba también a
sw.js, al manifest y a los iconos, que no llevan hash
en el nombre. La caché larga es correcta para archivos como
/assets/index-a1b2c3.js, porque si cambia el contenido cambia
el nombre. No lo es para archivos con nombre fijo.
La
guía de web.dev sobre el ciclo de vida
aclara el matiz: desde Chrome 68 el navegador ignora las cabeceras de
caché al comprobar si hay un sw.js nuevo, salvo que la
opción updateViaCache diga otra cosa. O sea, el propio
archivo del service worker suele salvarse. Lo que sí respeta la caché son
los scripts cargados con importScripts(), y respetan toda su
vida los iconos, el manifest y cualquier archivo sin hash que el
service worker o la página lean. Además otros navegadores y proxies
intermedios no siempre se comportan igual, así que no dependas de ese
atajo.
La regla que aplicamos desde entonces:
// Solo la carpeta con hash lleva caché larga
app.use('/assets', express.static('dist/assets', {
maxAge: '1y',
immutable: true,
}));
// Todo lo demás se revalida siempre
app.use(express.static('dist', {
setHeaders(res, ruta) {
res.setHeader('Cache-Control', 'no-cache');
},
})); no-cache no significa "no guardar": significa "revalida
antes de usar", y suele resolverse con una respuesta 304 muy barata. Nos
quita el riesgo sin perder velocidad.
Trampa 2: actualizar no es lo mismo que activar
Síntoma: el sw.js nuevo ya está en el
servidor, pero la app sigue ejecutando la lógica vieja aunque recargues.
Esto es el diseño del ciclo de vida, no un fallo. Según web.dev, un service worker actualizado se instala y luego espera hasta que el anterior no controle ningún cliente. Recargar la página no basta, porque durante la navegación el worker viejo sigue controlando. Hay que cerrar todas las pestañas o ventanas de la app. En una PWA instalada en el teléfono, "cerrar" significa sacarla del selector de apps.
skipWaiting() evita la espera, pero con un riesgo que la
propia guía advierte: páginas cargadas con el worker viejo pueden pasar a
ser atendidas por el nuevo a mitad de camino. Para un panel que solo
reenvía peticiones eso es inocuo. Si tu worker cachea el shell de la app,
pruébalo bien antes de activarlo.
Cuando queríamos saber si había un despliegue nuevo sin inventar números
de versión, usamos un truco simple: el empaquetador (Vite en nuestro caso)
pone un hash del contenido al nombre del bundle. La app lee el nombre del
<script> que está ejecutando, consulta el
index.html actual con cache: 'no-store' y, si el
nombre cambió, muestra un aviso para recargar.
Trampa 3: qué cachear y qué no
Para un panel de datos en vivo, el service worker correcto es casi vacío:
solo responde a fetch pasando la petición a la red. Sin
precache, sin caché de nada. Una respuesta guardada mostraría un estado
viejo como si fuera el actual, que en un monitor es peor que no mostrar
nada.
self.addEventListener('fetch', (event) => {
event.respondWith(fetch(event.request));
});
Para una app con un shell estático, como una de estudio, la estrategia es
red primero para el shell y caché solo como respaldo sin
conexión. Las rutas de la API nunca se cachean. Y los archivos
regenerables que viven siempre en la misma URL, como audios generados,
necesitan Cache-Control: no-cache explícito, o te sirven la
versión anterior después de regenerarlos.
Trampa 4: la barra de estado y la isla dinámica de iOS
Síntoma: instalada en un iPhone con isla dinámica, la cabecera de la app queda parcialmente tapada por la isla.
La causa fue la etiqueta
apple-mobile-web-app-status-bar-style con el valor
black-translucent: dibuja la web debajo de la barra
de estado. Con default la barra recupera su espacio. Si
quieres contenido a pantalla completa, tendrás que compensar tú con
env(safe-area-inset-top) y compañía, y para que esas
variables valgan algo hace falta viewport-fit=cover en el
meta viewport.
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<meta name="mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
/* CSS */
.cabecera { padding-top: env(safe-area-inset-top); }
.barra-inferior { padding-bottom: env(safe-area-inset-bottom); } Fíjate que van los dos meta de app web. El prefijado de Apple se mantiene porque las versiones de iOS anteriores a 16.4 no leen el manifest. El estándar sin prefijo evita el aviso de obsolescencia que muestra Chrome cuando aparece solo el de Apple.
Trampa 5: theme-color que no obedece
Síntoma: la app tiene modo claro y oscuro con un botón, pero la barra del sistema no sigue el cambio manual.
Si declaras theme-color con media="(prefers-color-scheme: dark)",
el navegador usa el primer meta cuya condición se cumpla.
Cambiar su atributo content desde JavaScript no siempre
gana, porque se evalúa según la preferencia del sistema, no la de tu
botón. Para forzar un tema elegido, antepón en el head un
meta propio sin media query y actualízalo desde tu interruptor. Y si
guardas la preferencia, aplica el tema con un script en línea al inicio
del head, antes de pintar. Si no, ves un destello del tema
equivocado en cada apertura.
Trampa 6: los cambios en el HTML no llegan a iOS
Una app instalada en iPhone no vuelve a leer el index.html
por sí sola. Si cambiaste metadatos (iconos, colores, etiquetas), hay que
cerrarla del todo o reinstalarla una vez. Lo aprendimos tras creer que un
arreglo no había funcionado cuando solo no se había recargado. Avísate a
ti mismo esto antes de dar por fallido un cambio de head.
Cómo probarlo antes de decir "listo"
- En Chrome, abre DevTools, pestaña Application, sección Manifest. No debe haber errores y debe aparecer la opción de instalar.
- En la misma pestaña, mira Service Workers y comprueba que el estado sea activado y que no haya uno "en espera".
- Revisa las cabeceras:
curl -I https://tu-sitio/sw.jsdebe mostrarno-cache, y un archivo de/assets/debe mostrar la caché larga. - Instala en un Android y en un iPhone reales. Comprueba la barra de estado, la isla dinámica y la zona inferior en horizontal y vertical.
- Publica un cambio visible, cierra la app del todo, ábrela y confirma que llegó la versión nueva.
- Prueba el modo oscuro del sistema y, si lo tienes, tu interruptor manual.
Checklist final
- HTTPS, manifest con iconos 192 y 512 px,
display: standalone. - Icono maskable aparte, con margen suficiente.
apple-touch-icondeclarado para iOS.- Service worker registrado, con la estrategia de caché adecuada al tipo de datos.
- Caché larga solo para archivos con hash;
sw.js, manifest e iconos conno-cache. - Los dos meta de app web y
status-bar-style: default. viewport-fit=coveryenv(safe-area-inset-*)en cabeceras y barras fijas.- Un mecanismo para avisar de nueva versión.
- Instrucciones visibles de instalación para iPhone.
- Probado instalada, en teléfono real, durante varios días.
Una PWA no se da por terminada cuando pasa la auditoría. Se da por terminada cuando la instalaste, la usaste unos días, publicaste un cambio y comprobaste que llegó.