Cómo convertir tu sitio web en una progressive web app

Cómo convertir tu sitio web en una PWA (código probado) | We.Inc

Haz que cualquier sitio web se pueda instalar y funcione sin conexión: un generador de manifest, un service worker probado, un botón de instalar, los límites en iPhone y la configuración en Vite o Next.js.

Cómo convertir tu sitio web en una progressive web app

Para convertir un sitio web en una progressive web app, sírvelo por HTTPS, añade un manifest.webmanifest con un nombre, start_url, modo de visualización e iconos de 192 y 512 píxeles, enlázalo desde todas las páginas y registra un service worker que guarde archivos en caché para usarlos sin conexión. Los navegadores Chromium ofrecerán entonces instalarla; quienes usan Safari la añaden desde Compartir.

Las tres partes de una PWA

Parte
Qué hace

Nombre, iconos, colores y cómo se abre la app

Service worker (sw.js)
Guarda archivos en caché para que las páginas carguen sin conexión

HTTPS
Obligatorio para los service workers y la instalación

Rellena el formulario para obtener un manifest y las etiquetas del head que debes pegar, y luego copia el service worker y el script de instalación. El worker de esta página se ejecutó en un navegador real con la red cortada antes de publicarlo.

Crea iconos de 192 y 512 píxeles, más una versión maskable con el logo dentro del 80 por ciento central.
Genera el manifest con el formulario, guárdalo como manifest.webmanifest en la raíz del sitio y pega las etiquetas del head en todas las páginas.
Guarda sw.js, offline.html y el script de registro, y enumera tus archivos principales en PRECACHE.
Abre Chrome DevTools, panel Application: revisa Manifest para ver problemas de instalación y Service workers para ver el worker en marcha. Marca Offline y recarga para probar.
Cuando cambies archivos en caché, sube VERSION para que los visitantes que vuelven reciban los nuevos.

Sirve sw.js desde la raíz del sitio. Un worker solo controla las páginas de su propia carpeta o de las inferiores.
No guardes el propio sw.js con cabeceras de caché HTTP largas; los navegadores lo revisan para buscar actualizaciones.
Mantén corta la lista de precaché. Todo lo que contiene se descarga en la primera visita.
En iPhone, explica a la gente cómo instalar: Compartir y luego Añadir a pantalla de inicio. No hay ningún aviso que puedas activar.
Prueba sin conexión deteniendo también tu servidor local, además de usar la casilla Offline, para que fallen también las peticiones del propio worker.

Preguntas frecuentes

¿Una PWA necesita un service worker para poder instalarse?

En el Chrome actual, no: un manifest válido, HTTPS y algo de interacción del usuario bastan para la opción de instalar. Aun así te conviene un worker, porque sin él la app instalada muestra la página de error del navegador cuando no hay conexión.

¿Funcionan las PWA en iPhone?

Sí, con límites. En Safari se instalan desde el menú Compartir, no existe el evento de aviso de instalación y las notificaciones push solo funcionan en un sitio añadido a la pantalla de inicio en iOS 16.4 o posterior. La caché sin conexión sí funciona.

¿Por qué no aparece nunca mi botón de instalar?

beforeinstallprompt solo se dispara en navegadores Chromium, solo cuando se cumplen los criterios de instalación y no cuando la app ya está instalada. Revisa la sección Manifest del panel Application de DevTools para ver el motivo.

¿Cómo reviso una PWA ahora que Lighthouse no tiene puntuación PWA?

Lighthouse 12 eliminó la categoría PWA. Usa el panel Application de Chrome DevTools: la vista Manifest enumera los errores de instalabilidad y los problemas de iconos, y la vista Service workers muestra el registro, las actualizaciones y un interruptor Offline.

¿Cómo actualizo una PWA después de un lanzamiento?

Cambia la VERSION de la caché en sw.js. El navegador detecta el worker modificado, lo instala y el paso activate elimina las cachés antiguas. Con skipWaiting y clients.claim, el nuevo worker toma el control en la siguiente carga.

Primero la caché o primero la red

Cache-first responde desde la caché y solo va a la red para lo que no tiene guardado. Es rápido y adecuado para archivos cuyo contenido nunca cambia con el mismo nombre, como scripts con hash, fuentes e iconos.
Network-first pregunta al servidor y solo usa la caché cuando eso falla. Encaja con las páginas HTML, donde mostrar una copia vieja tras una actualización confundiría a la gente. El worker de arriba usa ambos: network-first para las cargas de página y cache-first para todo lo demás.

Errores habituales

Registrar el worker desde una ruta de subcarpeta como /js/sw.js, lo que lo limita a las páginas de /js/.
Olvidar cambiar VERSION, de modo que los visitantes que vuelven conservan CSS y scripts antiguos durante semanas.
Guardar en caché respuestas de otros sitios o respuestas de error. El worker de arriba ignora las peticiones de otros orígenes y solo guarda las respuestas correctas de recursos.
Probar solo en Chrome. Abre el sitio en un iPhone para ver lo que reciben realmente quienes usan Safari.

Qué obtienes y los límites en iPhone

Instalar da a tu sitio su propio icono y una ventana sin barra de direcciones. Un service worker añade páginas sin conexión. Push necesita ambas cosas, y Apple solo lo permite para sitios que el usuario ha añadido a la pantalla de inicio.

Qué puede hacer una PWA, por plataforma

Función
Chrome / Edge (escritorio, Android)
Safari en iPhone y iPad
Firefox

Instalar en la pantalla de inicio o el escritorio
Sí, con un aviso de instalación
Sí, a mano: Compartir y luego Añadir a pantalla de inicio
Android: sí. Escritorio: limitado, revisa tu versión

Botón de instalar propio (beforeinstallprompt)
Sí
No
No

Sin conexión con un service worker
Sí
Sí
Sí

Notificaciones web push
Sí
Solo para un sitio añadido a la pantalla de inicio, iOS 16.4 o posterior
Sí

Almacenamiento duradero
Sí, puede eliminarse si falta espacio
En pestañas de Safari, el almacenamiento escrito por scripts puede borrarse tras 7 días de uso del navegador sin visitar el sitio; las apps de la pantalla de inicio llevan su propio recuento
Sí, puede eliminarse si falta espacio

Sincronización en segundo plano
Sí
No
No

Un service worker que funciona

Tres archivos hacen que un sitio funcione sin conexión: el worker, una página de respaldo y unas pocas líneas para registrarlo. Ejecutamos exactamente estos archivos en localhost en Chromium: el worker se instaló, la caché se llenó y, con el servidor detenido, la página de inicio cargó desde la caché mientras que una página nunca visitada mostró offline.html.

sw.js: un service worker mínimo que funciona sin conexión

Las páginas prueban primero la red para que la gente vea contenido actualizado, luego recurren a una copia en caché y después a offline.html. Archivos como CSS, scripts e iconos salen primero de la caché. Cambiar VERSION hace que el siguiente paso activate elimine las cachés antiguas.

offline.html: la página de respaldo

Haz que sea autónoma: estilos en línea y ningún archivo externo, porque puede que no se pueda acceder a nada más cuando se muestre.

Un botón de instalar

app.js: registra el worker y muestra un botón de instalar

El evento beforeinstallprompt solo se dispara en navegadores Chromium (Chrome, Edge, Samsung Internet, Opera). Safari y Firefox nunca lo envían, así que allí el botón queda oculto y la gente usa el menú del propio navegador.

Criterios de instalación actuales

Chrome ya no exige un service worker para ofrecer la instalación; lo que revisa es el manifest y los elementos de abajo. Lighthouse 12 eliminó su categoría PWA, así que revisa la instalabilidad en Chrome DevTools: panel Application y luego Manifest, que enumera cualquier problema en Installability.

Requisitos de instalación de Chrome

Requisito
Detalle

HTTPS
Servido de forma segura. localhost cuenta como seguro para pruebas.

Nombre en el manifest
name o short_name

Iconos en el manifest
Al menos un icono de 192 px y otro de 512 px

Presente en el manifest

fullscreen, standalone, minimal-ui o window-controls-overlay

Ausente o false

Interacción
El visitante ha hecho clic o tocado la página al menos una vez y ha pasado algo de tiempo en ella

Configuración en Vite y Next.js

Vite: vite-plugin-pwa

Instálalo con npm i -D vite-plugin-pwa. El plugin escribe el manifest y genera un service worker de Workbox al compilar, así que no tienes que escribir sw.js a mano. Pon los iconos en public/.

Next.js App Router: app/manifest.ts

Next.js sirve este archivo en /manifest.webmanifest y añade la etiqueta link por ti. Para el soporte sin conexión, pon el sw.js de arriba en public/ y regístralo desde un pequeño componente de cliente.

Next.js: registra public/sw.js desde un componente de cliente

Renderízalo una vez en app/layout.tsx. Omite el registro en desarrollo para que una compilación en caché no oculte tus cambios.

Nombre de la app

Nombre corto (bajo el icono)

URL de inicio

Carpeta de iconos

Color del tema

Color de fondo

Copiar

Generador de manifest

Visualización

Incluir un icono maskable

Guarda tus iconos como icon-192.png e icon-512.png (e icon-512-maskable.png) en la carpeta de iconos.

Cómo convertir tu sitio web en una progressive web app

Cómo convertir tu sitio web en una PWA (código probado) | We.Inc