# Construye tu primera PWA básica

**Published by:** [Frexus](https://paragraph.com/@frexus-2/)
**Published on:** 2025-09-08
**URL:** https://paragraph.com/@frexus-2/construye-tu-primera-pwa-b-sica

## Content

ObjetivoQue 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 y prerrequisitosNivel: 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.Materiales / herramientas necesariasNode.js / npmPlantilla Vite Reactvite-plugin-pwa (envuelve Workbox y simplifica la generación del service worker)Opcional: workbox-window si decides registrar manualmenteChrome DevTools (para Lighthouse y testing)Flujo de la actividad (pasos detallados)Paso 0 — Lee el caso de estudioLee la historia de Clara para contextualizar decisiones técnicas (qué herramientas escogió y por qué).Paso 1 — Crea el proyecto con Vite + ReactEn la terminal:npm create vite@latest mi-pwa -- --template react cd mi-pwa npm install 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.)Paso 2 — Instala y configura el plugin PWAInstala el plugin:npm install -D vite-plugin-pwa 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: [...] } }) ] }) Coloca iconos pwa-192x192.png y pwa-512x512.png en public/ o src/assets según tu configuración.Paso 3 — Añade el registro del service workerCon 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.Paso 4 — Añade manifest.json y asegúrate del enlaceSi 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.Paso 5 — Define estrategias de caché (opcional pero recomendado)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.Paso 6 — Prueba en desarrollo y en producción localDesarrollo:npm run dev #abre http://localhost:5173 En Chrome DevTools → Application → Manifest y Service Workers verifica que la app sea detectada como PWA.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.Paso 7 — Pruebas con LighthouseAbre 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é).Paso 8 — Validación final y entregaConfirma que la app se instala (display standalone) y tiene contenido usable offline (al menos la pantalla principal).Saca capturas de:Prompt de instalaciónApp funcionando en modo offlineReporte Lighthouse o puntaje PWASube código a repositorio y comparte enlace + capturas como entregable.Errores comunes & soluciones rápidasEl 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.Extensiones (desafíos opcionales)Añadir notificaciones push (usar Firebase Cloud Messaging o Web Push).Implementar Background Sync para enviar datos cuando vuelva la conexión.Optimizar imágenes y añadir lazy-loading, mejorando puntuación de rendimiento.Añadir pruebas automáticas para el service worker (p. ej. con Workbox en build).Relación con el caso de Clara (reflexión breve)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.

## Publication Information

- [Frexus](https://paragraph.com/@frexus-2/): Publication homepage
- [All Posts](https://paragraph.com/@frexus-2/): More posts from this publication
- [RSS Feed](https://api.paragraph.com/blogs/rss/@frexus-2): Subscribe to updates