Que el estudiante identifique y aplique herramientas, frameworks y librerías clave (React, Vite, vite-plugin-pwa / Workbox, manifest, service workers y Lighthouse) para convertir una web simple en una Progressive Web App instalable y usable offline.

• Nivel: principiante-intermedio (conocimientos básicos de HTML, CSS y JavaScript).

• Prerrequisitos:

  • Node.js (v16+ recomendado) y npm instalados.

  • Familiaridad básica con React (JSX, componentes).

  • Editor de código (VSCode recomendado).

  • Navegador Chrome o Chromium para pruebas y Lighthouse.

• Node.js / npm

• Plantilla Vite React

• vite-plugin-pwa (envuelve Workbox y simplifica la generación del service worker)

• Opcional: workbox-window si decides registrar manualmente

• Chrome DevTools (para Lighthouse y testing)

• Lee la historia de Clara para contextualizar decisiones técnicas (qué herramientas escogió y por qué).

1. En la terminal:

npm create vite@latest mi-pwa -- --template react
cd mi-pwa
npm install

1. Abre el proyecto en tu editor. (Nota: si prefieres Create React App o Next.js puedes adaptar, pero en esta guía usamos Vite por su rapidez.)

1. Instala el plugin:

npm install -D vite-plugin-pwa

1. Abre vite.config.js (o vite.config.ts) y añade la configuración mínima:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      includeAssets: ['favicon.ico', 'robots.txt', 'apple-touch-icon.png'],
      manifest: {
        name: 'Mi PWA de Ejemplo',
        short_name: 'MiPWA',
        description: 'Una PWA de ejemplo creada en el taller',
        theme_color: '#317EFB',
        icons: [
          {
            src: 'pwa-192x192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: 'pwa-512x512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      },
      workbox: {
        // Aquí puedes añadir estrategias de caché si lo deseas
        // runtimeCaching: [...]
      }
    })
  ]
})

1. Coloca iconos pwa-192x192.png y pwa-512x512.png en public/ o src/assets según tu configuración.

Con vite-plugin-pwa muchas cosas se registran automáticamente, pero puedes registrar con un hook en React:

En src/main.jsx (o index.js):

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'
import { registerSW } from 'virtual:pwa-register'

const updateSW = registerSW({
  onNeedRefresh() {},
  onOfflineReady() {}
})

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)

Si quieres mayor control manual, instala workbox-window y registra el service worker con eventos para waiting, activated, etc.

Si usas el plugin, el manifest se inyecta, pero verifica en index.html que exista:

<link rel="manifest" href="/manifest.webmanifest" />

Abre manifest.webmanifest y confirma name, short_name, icons, start_url, display: "standalone" y background_color.

En vite.config.js dentro de VitePWA({ workbox: { runtimeCaching: [...] }}) puedes añadir reglas, por ejemplo:

workbox: {
  runtimeCaching: [
    {
      urlPattern: /^https:\/\/api\.miapp\.com\/.*$/,
      handler: 'NetworkFirst',
      options: {
        cacheName: 'api-cache',
        expiration: { maxEntries: 50, maxAgeSeconds: 24 * 60 * 60 }
      }
    },
    {
      urlPattern: /\.(?:png|jpg|jpeg|svg|gif)$/,
      handler: 'CacheFirst',
      options: {
        cacheName: 'image-cache',
        expiration: { maxEntries: 60, maxAgeSeconds: 30 * 24 * 60 * 60 }
      }
    }
  ]
}

Estas estrategias equilibran frescura y disponibilidad offline.

Desarrollo:

npm run dev
#abre http://localhost:5173

En Chrome DevTools → Application → Manifest y Service Workers verifica que la app sea detectada como PWA.

1. Prueba build (simular producción local):

npm run build 
npm run preview

o usa un servidor estático que soporte service workers en localhost

Nota: los service workers funcionan en localhost y sobre HTTPS. Para deploy remoto debes usar HTTPS.

• Abre la app en Chrome → DevTools → Lighthouse → Genera un reporte (elige categoría PWA).

• O desde CLI:

npx lighthouse http://localhost:5173 --only-categories=pwa --view

Interpreta el reporte: corrige problemas señalados (manifest, service worker, carga inicial, caché).

• Confirma que la app se instala (display standalone) y tiene contenido usable offline (al menos la pantalla principal).

• Saca capturas de:

  • Prompt de instalación

  • App funcionando en modo offline

  • Reporte Lighthouse o puntaje PWA

• Sube código a repositorio y comparte enlace + capturas como entregable.

• El service worker no se instala: borra caches e intenta con Service Workers → Unregister y recarga. En desarrollo usa npm run build + preview para simular producción.

• La app no se muestra como instalable: revisa manifest.start_url, display: "standalone" y que el manifest esté bien enlazado.

• Caché mostrando contenido antiguo: implementa versionado y estrategias como skipWaiting() y clients.claim() en el SW para forzar actualización.

• Problemas de scope: coloca el service worker en el root (/) si quieres caché global.

1. Añadir notificaciones push (usar Firebase Cloud Messaging o Web Push).

2. Implementar Background Sync para enviar datos cuando vuelva la conexión.

3. Optimizar imágenes y añadir lazy-loading, mejorando puntuación de rendimiento.

4. Añadir pruebas automáticas para el service worker (p. ej. con Workbox en build).

• En la actividad aplicas la misma lógica que Clara: evaluar opciones (framework vs librería vs herramienta), elegir por ecosistema y documentación (React + vite-plugin-pwa), y usar auditoría (Lighthouse) para validar decisiones. El aprendizaje no es solo técnico: valorar usabilidad y experiencia del usuario.