🛠️ Guía Pro: Cómo crear tu PWA en Next.js 16 desde Cero

¡Hola! Que alegría que estés aquí. Personalmente, creo que las PWAs son el futuro de la web: combinan lo mejor de una página y una app nativa. He diseñado esta guía para que transformes tu proyecto Next.js en algo increíble, paso a paso y sin complicaciones.

🚀 Ver Demo Interactiva

📑 Índice de Contenidos

¿Por qué crear una PWA?
Requisitos Previos
Paso 1: Inicializar el Proyecto
Paso 2: Instalar la Librería PWA
Paso 3: Preparar los Iconos
Paso 4: El Manifiesto (manifest.json)
Paso 5: Soporte para TypeScript
Paso 6: Configuración Master (next.config.ts)
Paso 7: Vinculación en el Layout
Paso 8: Configurar Webpack y Scripts
Paso 9: Limpieza de Git
Paso 10: Página Offline de Respaldo
Paso 11: Verificación Final
Consejos de Pro y Recursos

🚀 ¿Por qué crear una PWA?

Instalación: Los usuarios pueden añadir tu web a su pantalla de inicio sin usar una App Store.
Velocidad: Gracias a la caché inteligente, la app carga instantáneamente.
Offline: Tus usuarios pueden interactuar con la app aunque no tengan señal.
Engagement: Incrementa la retención de usuarios con una experiencia nativa.

📋 Requisitos Previos

Node.js (Versión 18 o superior).
Next.js 16.1.1+ (App Router recomendado).
Conocimientos básicos de React y terminal.

Paso 1: Inicializar el Proyecto

Si empiezas desde cero, crea tu proyecto:

npx create-next-app@latest mi-pwa

(Recomendado: TypeScript, ESLint, Tailwind, App Router).

Paso 2: Instalar la Librería PWA

Usaremos next-pwa, la librería líder para gestionar el Service Worker (el "motor" que permite el modo offline).

npm install next-pwa

Paso 3: Preparar los Iconos 🎨

Tu app necesita una identidad visual. Debes colocar tus iconos en public/.

Crea iconos en formato .png de varios tamaños (el más importante es 512x512).
Herramienta Útil: Usa PWA Asset Generator para generar todos los tamaños automáticamente.

Paso 4: Crear el Manifiesto (`manifest.json`)

Este archivo le dice al sistema operativo cómo mostrar tu app. Crea public/manifest.json:

{
  "name": "Mi Increíble PWA",
  "short_name": "MiApp",
  "description": "Una aplicación web de alto rendimiento",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    { "src": "/icon-192x192.png", "sizes": "192x192", "type": "image/png" },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Paso 5: Arreglar TypeScript (Solo si usas TS) 🟦

Evita errores de tipos creando el archivo next-pwa.d.ts en la raíz:

declare module "next-pwa";

Paso 6: Configurar Next.js (`next.config.ts`)

Activa el plugin en tu configuración principal. Nota: Desactivamos la PWA en desarrollo para mayor comodidad al programar.

import type { NextConfig } from "next";
import withPWAInit from "next-pwa";

const withPWA = withPWAInit({
  dest: "public",
  register: true,
  skipWaiting: true,
  disable: process.env.NODE_ENV === "development",
});

const nextConfig: NextConfig = {
  /* Otras configuraciones */
};

export default withPWA(nextConfig);

Paso 7: Vincular la PWA en el Layout

Añade las referencias en app/layout.tsx. Esto es lo que activa el botón de instalación.

export const metadata: Metadata = {
  title: "Mi PWA",
  manifest: "/manifest.json",
  appleWebApp: {
    capable: true,
    statusBarStyle: "default",
    title: "Mi PWA",
  },
};

export const viewport = {
  themeColor: "#000000",
};

Paso 8: Configurar los Comandos (`package.json`)

Debido a que next-pwa usa Webpack, debemos forzar este motor en el comando de desarrollo:

"scripts": {
  "dev": "next dev --webpack",
  "build": "next build --webpack",
  "start": "next start"
}

Paso 9: Mantener tu casa limpia (`.gitignore`) 🧹

Evita subir los archivos generados automáticamente por el Service Worker. Añade esto a .gitignore:

# PWA files
**/public/sw.js
**/public/workbox-*.js
**/public/worker-*.js
**/public/sw.js.map
**/public/workbox-*.js.map
**/public/worker-*.js.map

Paso 10: Página Offline de Respaldo 📶

Asegura una experiencia profesional cuando no haya conexión. Crea app/~offline/page.tsx:

"use client";

export default function OfflinePage() {
  return (
    <div style={{ textAlign: "center", padding: "50px" }}>
      <h1>📶 Vaya, estás Offline</h1>
      <p>
        Las secciones que ya visitaste funcionan, pero esta requiere internet.
      </p>
      <button onClick={() => window.location.reload()}>
        Intentar conectar
      </button>
    </div>
  );
}

Paso 11: Cómo verificar que todo funciona ✅

Prueba en Producción (Esencial)

Ejecuta npm run build para compilar.
Ejecuta npm run start para arrancar.
Abre Chrome/Edge y ve a la URL.
Verás el mensaje "Service Worker registered" en la consola.
Verás el icono de "Instalar App" en la barra de direcciones.

Paso 12: Consejos de Pro y Recursos 🌟

Consejos para una PWA de 10

Iconos Maskable: Asegúrate de que el icono de 512px tenga el propósito maskable para que Android no lo recorte mal.
HTTPS: Fuera de localhost, las PWA solo funcionan bajo HTTPS. Usa Vercel o Netlify para despliegues rápidos y seguros.
Lighthouse: Usa la herramienta de auditoría de Chrome para verificar que cumples con todos los estándares de PWA.

🔗 Recursos y Código Fuente

Si quieres revisar el código completo de esta implementación o probar la demo final, utiliza los siguientes enlaces:

🚀 Ver Demo en Vivo

📂 Clonar Repositorio en GitHub

⚠️ Errores Comunes (¡No te frustres!)

A veces las cosas no salen a la primera. Aquí te dejo lo que suelo revisar yo cuando algo falla:

¿Iconos perdidos?: Casi siempre es una ruta mal escrita en el manifest.json. Verifica que el nombre del archivo en /public coincida exactamente.
¿No ves los cambios?: El Service Worker es muy persistente. Te recomiendo borrar la caché del sitio desde la pestaña "Application" de la consola (F12) para forzar la actualización.
¿Botón de instalar no aparece?: Recuerda que en escritorio no siempre sale el popup, a veces es solo un pequeño icono en la barra de direcciones. ¡Y asegúrate de estar en HTTPS si no estás en localhost!

¡Felicidades por llegar hasta aquí! Ahora tienes una PWA profesional lista para impresionar a tus usuarios. Si te ha servido, no dudes en compartirla. 🚀