Ek hou daarvan om gereedskap te bou wat nie net werk nie - hulle My span is lank genoeg in die trenches van Next.js om presies te weet wat pyn. - 'n drop-in-pakket wat volle PWA-ondersteuning in jou Next.js-toepassing bedryf sonder dat jy jou hare uitraai. Gaan uit jou pad next-pwa-pack Die Backstory (aka: Waarom ek hierdie ding geskryf het) Elke keer as 'n kliënt "PWA-ondersteuning" genoem het, het ek myself gebreek. Ek het bestaande biblioteke probeer. Te veel magie. Tone van konfig. Of net heeltemal onverenigbaar met - wat, by die manier, ons ten volle aangenomen het. ek wou: App Router Server-side cache hervalidering App router integrasie. Sinkronisasie tussen tabs. Clean API vir die bestuur van die cache van die backend. In plaas daarvan het ek uiteindelik die dienswerkers met die hand geskryf. Tuning cache TTLs. Omgaan met opdatering logika. Beheer stale kliënte. Handmatig die caches weg te wrap elke keer as ons gestuur het. En moenie selfs my begin op gebruikers wat nie updates sien nie totdat hulle hard-verfris het nie. Ek het iets nodig gehad wat dood eenvoudig, voorspelbaar en gevechtstest is. Gebou Wat het in die Die volgende pakket Die volgende pakket Stap een was om 'n minimale diensarbeider te skryf: Cache HTML met TTL. Omgaan met statische aktiva. Werk offline, soos 'n ware PWA moet. Toe het ek 'n boodskapstelsel bygevoeg sodat die kliënt met die diensarbeider kon praat - byvoorbeeld, om 'n cache te breek of cache heeltemal te deaktiveer. Daarna het ek 'n paar skrywers geskryf: Kopieer sw.js, manifest.json en offline.html in jou projek. Injecteer 'n bediener aksie genaamd revalidatePWA wat jy oral kan gebruik (API roetes, bediener aksie, bediener komponente - neem jou keuse). Vir volle App Router en SSR / Edge-ondersteuning, het ek alles in 'n hoër orde-funksie verpak: Een import, een oproep – gedoen. withPWA Ek het ook in tab-synchronisasie gebou. omdat gebruikers oop jou app in 3 tabs en verwag dat hulle magies in sinchronisering sal opdat. + die Die gebeurtenisse. wil localStorage storage Die resultaat? 'n pakket wat net werk. Geen swart magie konfigurasie nie. Geen herschryf kerndele van jou app nie. Wat jy kry met Die volgende pakket Die volgende pakket Sodra jy dit geïnstalleer het, kry jy: Registrasie van dienswerkers uit die boks - geen boilerplate nie. Offline fallback met 'n aanpasbare offline.html. Auto-geskopieerde lêers wat jy kan tweak (manifest, SW, ens.). Cache beheer API - duidelik, opdater, deaktiveer, alles programmaties. Synchroniseer tussen tabs — geen stabiele inhoud in multi-tab-opstellings nie. Ontwikkel paneel vir real-time PWA toestand tydens plaaslike ontwikkeling. Server-side hervalidering ondersteuning deur middel van bediener aksie, API roetes, of eksterne webhook integrasies. Jy kan die pakket hier kry: https://github.com/dev-family/next-pwa-pack Wat gebeur as jy dit installeer Die installeer script kopieer PWA boilerplate in : /public sw.js – jou dienswerker met cachelogika. offline.html – fallback bladsy vir die offline modus. manifest.json – tweak dit om in jou app te pas. ⚠️ Bestaande lêers sal nie oorskryf word nie - dit respekteer jou instelling. As jy die kopie handmatig wil uitlok: node node_modules/next-pwa-pack/scripts/copy-pwa-files.mjs # or npx next-pwa-pack/scripts/copy-pwa-files.mjs Die server aksie Dit word ook by jou of Bestand afhanklik van jou folder struktuur: revalidatePWA app/actions.ts src/app/actions.ts "use server"; export async function revalidatePWA(urls: string[]) { const baseUrl = process.env.NEXT_PUBLIC_HOST || "http://localhost:3000"; const res = await fetch(`${baseUrl}/api/pwa/revalidate`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ urls, secret: process.env.REVALIDATION_SECRET, }), }); return res.json(); } As die lêer nie verskyn nie, kan jy: node node_modules/next-pwa-pack/scripts/copy-pwa-server-actions.mjs Konfigureer jou Geskryf deur: Jason Geskryf deur: Jason Na die installasie, moenie vergeet om te pas : /public/manifest.json { "name": "My App", "short_name": "App", "description": "My amazing PWA app", "start_url": "/", "display": "standalone", "background_color": "#ffffff", "theme_color": "#000000", "icons": [ { "src": "/icons/icon-192x192.png", "sizes": "192x192", "type": "image/png" }, { "src": "/icons/icon-512x512.png", "sizes": "512x512", "type": "image/png" } ] } Gooi jou ikoon in of die pad van die boonste. niks fancy. public/icons/ Snel begin: Wire It Up Verwyder jou layout in die En die magie klop in: PWAProvider import { PWAProvider } from "next-pwa-pack"; export default function layout({ children }) { return <PWAProvider>{children}</PWAProvider>; } As jy wil dat hervalidering van die bediener kant werk, moet jy ook jou middelsoftware opdater: // /middleware.ts import { withPWA } from "next-pwa-pack/hoc/withPWA"; function originalMiddleware(request) { // your logic here return response; } export default withPWA(originalMiddleware, { revalidationSecret: process.env.REVALIDATION_SECRET!, sseEndpoint: "/api/pwa/cache-events", webhookPath: "/api/pwa/revalidate", }); export const config = { matcher: ["/", "/(ru|en)/:path*", "/api/pwa/:path*"], }; Die HOC opsies: oorspronklikeMiddleware: jou basis middleware (bv, vir i18n of auth). revalidationSecret: geheime token om cache hervalidering af te sluit. sseEndpoint: SSE-stroompad (verandering as dit in konflik is). webhookPath: eindpunt om te tref vir die verfrissing van die cache (gebruik deur revalidatePWA). Binne die PWAProvider Voedselverskaffer die bundel 'n klomp dinge onder die hoed - en jy kan cherry-pick komponente ook: PWAProvider RegisterSW Verwys na die werknemer ( ). Hanteer foute gracieus. Jy kan die pad oorskry as nodig: /sw.js <PWAProvider swPath="/custom/sw.js">{children}</PWAProvider> CacheCurrentPage Intercepteer navigeer (insluitend SPA-styl oorgange), caches die huidige bladsy se HTML. SWRevalidateListener Kyk vir localStorage-gebeurtenisse en veroorsaak cache-verfrissing oor tabs. SSERevalidateListener Verwys na server-gestuurde gebeurtenisse van die Wanneer jou backend sê "hervalideer hierdie URL's," maak hierdie luisteraar seker dat kliënte dit doen. sseEndpoint DevPWAStatus Dev-only paneel wat jy kan aktiveer soos hierdie: <PWAProvider devMode>{children}</PWAProvider> Die vertonings: Online / Offline status Cache weergawe Update beskikbaarheid Eenklik gereedskap: skoon cache, onregistreer SW, verfriss, deaktiveer / aktiveer cache Wat die werknemer eintlik doen Die kern die hand: sw.js Die HTML Caching bladsye wat met TTL cached is (default: 10 min — tweakable in sw.js) Auto-hervalideer wanneer TTL verval Offline fallback as HTML ontbreek Statiese eiendom JS, CSS, beelde word vir ewig cached Alleen caches ontvang versoekings boodskap ondersteuning Ondersteun hierdie aksies van die kliënt: CACHE_CURRENT_HTML van die Geskryf deur_URL Disable_Cache / Onttrek Vliegtuig - wag CLEAR_STATIC_CACHE deur Offline mode Dien offline.html as netwerk en cache beide misluk Probeer om te verfriss wanneer terug aanlyn Gebruik In die Middellandse withPWA verwyder Dit is waar Dit bring cache hervalidering na SSR en Edge Middleware - met SSE ondersteuning en alles. next-pwa-pack export default withPWA(originalMiddleware, { revalidationSecret: process.env.REVALIDATION_SECRET!, sseEndpoint: "/api/pwa/cache-events", webhookPath: "/api/pwa/revalidate", }); Params: oorspronklikeMiddleware: jou bestaande middleware logika (auth, i18n, ens.) revalidationSecret: sodat niemand anders jou cache kan poke nie sseEndpoint: oorskakel as iets anders hierdie roete gebruik webhookPath: gebruik deur die bediener of eksterne stelsels om spesifieke URL's te hervalideer Real-Wereld gebruik gevalle Update Cache na data veranderinge import { updateSWCache } from "next-pwa-pack"; // After creating a blog post: const handleCreatePost = async (data) => { await createPost(data); updateSWCache(["/blog", "/dashboard"]); }; Update Cache van die server import { revalidatePWA } from "../actions"; await createPost(data); await revalidatePWA(["/my-page"]); Verwyder Cache op Logout import { clearAllCache } from "next-pwa-pack"; const handleLogout = async () => { await logout(); await clearAllCache(); router.push("/login"); }; Alle kliënt cache aksies import { clearAllCache, reloadServiceWorker, updatePageCache, unregisterServiceWorkerAndClearCache, updateSWCache, disablePWACache, enablePWACache, clearStaticCache, usePWAStatus, } from "next-pwa-pack"; // Examples: await clearAllCache(); await reloadServiceWorker(); await updatePageCache("/about"); await unregisterServiceWorkerAndClearCache(); await clearStaticCache(); updateSWCache(["/page1", "/page2"]); disablePWACache(); enablePWACache(); const { online, hasUpdate, swInstalled, update } = usePWAStatus(); API-roete vir eksterne cache-triggers As u buitelandse cache-verfrissings wil veroorsaak (bv. van 'n admin-paneel), is hier 'n API-route wat u kan gebruik: // app/api/webhook/revalidate/route.ts import { NextRequest, NextResponse } from "next/server"; import { revalidatePWA } from "@/app/actions"; import { revalidateTag } from "next/cache"; import { FetchTags } from "@/app/api/endpoints/backend"; export async function POST(request: NextRequest) { try { const { tags, secret, urls } = await request.json(); if (secret !== process.env.REVALIDATION_SECRET) { return NextResponse.json({ error: "Unauthorized" }, { status: 401 }); } const validTags = Object.values(FetchTags); const invalidTags = tags?.filter((tag) => !validTags.includes(tag)) || []; if (invalidTags.length > 0) { return NextResponse.json( { error: `Invalid tags: ${invalidTags.join(", ")}` }, { status: 400 } ); } let successful = 0; let failed = 0; if (tags?.length) { const tagResults = await Promise.allSettled( tags.map((tag) => revalidateTag(tag)) ); successful = tagResults.filter((r) => r.status === "fulfilled").length; failed = tagResults.filter((r) => r.status === "rejected").length; } if (urls?.length) { await revalidatePWA(urls); } return NextResponse.json({ success: true, message: "Cache revalidation completed", tags, urls, successful, failed, timestamp: new Date().toISOString(), }); } catch (error) { console.error("Webhook revalidation error:", error); return NextResponse.json({ error: "Internal server error" }, { status: 500 }); } } Tref dit met: POST https://your-app.com/api/webhook/revalidate { "tags": ["faq"], "secret": "1234567890", "urls": ["/ru/question-answer"] } Debugging en DevTools Hier is wat jy kan kyk wanneer jy debug: Gaan na DevTools → Toepassing → Dienswerkers. Bevestig dat die werknemer geregistreer is. Kyk Cache Storage → html-cache-v2 om te sien of bladsye in die caches is. Simuleer offline in Netwerk → Offline en laai op. Jy moet offline.html sien. Console logs from the service worker help too: [PWA] Service Worker registered [SW] Cached: /about [SW] Revalidated and updated cache for: /blog Gotchas en Notes 'N Paar dinge wat jy moet weet voordat jy skip: Veiligheid PWA vereis HTTPS in produksie. Alleen GET versoekings word cached. Moenie sensitiewe data verberg nie. Die prestasie Die pakket raak nie die prestasie baseline van jou app nie. Dit verbeter herhaalde lading aansienlik. Konfig TTL is ingestel in sw.js (default: 10 minute). U kan URL's uit die caching uitsluit via CACHE_EXCLUDE. manifest.json moet op jou app aangepas word. revalidatePWA aksie is bewerkbaar - pas dit aan as nodig. metPWA en PWAProvider beide aanvaar opsies: export default function PWAProvider({ children, swPath, devMode = false, serverRevalidation = { enabled: true, sseEndpoint: "/api/pwa/cache-events" }, }: PWAProviderProps) { Wat is volgende Dit is geskryf vir Dit moet werk op ook - net nie uitgebreide toets nie. next-pwa-pack Next.js 15 Next.js 13 App Router Die geplande kenmerke: TTL config via opsies (geen bewerk sw.js) Push kennisgewing Pattern-gebaseerde cache beheer Prestasiemetriese vir cache-doeltreffendheid Dit is dit. As jy moeg is om die dienswerkers handmatig te bekamp, gee Jy gaan van nul na volle PWA-ondersteuning in een koffiepauze. next-pwa-pack Vrae, bugs, of terugvoer? Open 'n probleem of slaan ons op. die github.com/dev-familie/next-pwa-pak
