Saya suka membina alat yang tidak hanya berfungsi - mereka Pasukan saya telah berada dalam trench of Next.js cukup lama untuk tahu persis apa yang menyakitkan. - paket drop-in yang menyambung sokongan PWA penuh dalam aplikasi Next.js anda tanpa anda memotong rambut anda. keluar daripada jalan anda next-pwa-pack The Backstory (aka: Mengapa saya menulis perkara ini) Setiap kali klien menyebut "support PWA", saya memeluk diri saya. Saya cuba perpustakaan yang sedia ada. Terlalu banyak sihir. Tons of config. atau hanya sama sekali tidak bersesuaian dengan - yang, sebaliknya, kami telah sepenuhnya mengamalkan. saya mahu: App Router Pemulihan cache server. Integrasi App Router Sinkronkan mudah antara tab. Clean API untuk menguruskan cache daripada backend. Sebaliknya, saya akhirnya menulis pekerja perkhidmatan dengan tangan. Tuning cache TTLs. Berurusan dengan logik kemas kini. Menguruskan klien stale. Menghapuskan cache secara manual setiap kali kami menghantar. Dan jangan pun memulakan saya pada pengguna yang tidak melihat kemas kini sehingga mereka menyegarkan dengan sukar. Saya perlukan sesuatu yang mudah, mudah diprediksi, dan peperangan yang diuji. Pembinaan Apa yang masuk ke dalamnya next-pwa-pack NextPerkh Langkah satu ialah menulis seorang pekerja perkhidmatan minimum: Cache HTML dengan TTL. Menguruskan aset statik. Bekerja secara offline, seperti PWA sebenar. Kemudian saya menambah sistem mesej supaya klien boleh bercakap dengan pekerja perkhidmatan - contohnya, untuk memecahkan cache atau melumpuhkan caching sepenuhnya. Seterusnya, saya telah menulis beberapa skrip: Menyalin automatik sw.js, manifest.json, dan offline.html ke dalam projek anda. Menyuntikkan tindakan pelayan yang dipanggil revalidatePWA yang anda boleh gunakan di mana-mana sahaja (Rute API, tindakan pelayan, komponen pelayan - mengambil pilihan anda). Untuk sokongan penuh App Router dan SSR / Edge, saya membungkus segala-galanya dalam fungsi yang lebih tinggi: Satu import, satu panggilan - selesai. withPWA Saya juga telah membina dalam sinkronisasi tab. kerana pengguna buka aplikasi anda dalam 3 tab dan mengharapkan mereka untuk mengemas kini secara ajaib dalam sinkron. + daripada peristiwa yang akan localStorage storage Hasilnya? satu paket yang hanya berfungsi. Tiada konfigurasi sihir hitam. Tiada penulisan semula bahagian teras aplikasi anda. Apa yang anda dapatkan dengan next-pwa-pack NextPerkh Sebaik sahaja anda memasang, anda akan mendapat: Pendaftaran pekerja perkhidmatan di luar kotak - tiada boilerplate. Fallback Offline dengan tersuai offline.html. Fail yang disalin secara automatik yang anda boleh menyesuaikan (manifest, SW, dan lain-lain). API kawalan cache — jelas, mengemas kini, menonaktifkan, semua secara programmatik. Sinkronkan antara tab — tiada kandungan yang stable dalam setup pelbagai tab. Panel pembangunan untuk keadaan PWA masa nyata semasa pembangunan tempatan. Sokongan pengesahan semula di sisi pelayan melalui tindakan pelayan, laluan API, atau integrasi webhook luaran. Anda boleh simpan paket di sini: https://github.com/dev-family/next-pwa-pack Apa yang berlaku apabila anda memasang Skrip pemasangan automatik menyalin boilerplate PWA ke : /public sw.js – pekerja perkhidmatan anda dengan logik cache. offline.html – halaman balik untuk mod offline. manifest.json – tukar untuk menyesuaikan aplikasi anda. ⚠️ Fail yang sedia ada tidak akan tertulis berlebihan - ia menghormati setup anda. Jika anda ingin memulakan salinan secara manual: node node_modules/next-pwa-pack/scripts/copy-pwa-files.mjs # or npx next-pwa-pack/scripts/copy-pwa-files.mjs Tindakan Server Ia juga telah ditambah kepada atau Tergantung kepada struktur folder anda: 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(); } Jika fail itu tidak muncul, anda boleh menjalankan: node node_modules/next-pwa-pack/scripts/copy-pwa-server-actions.mjs Konfigurasi anda manifest.json Melayu.json Selepas memasang, jangan lupa untuk menyesuaikan : /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" } ] } Masukkan ikon anda ke dalam , atau tweak laluan di atas. tiada apa-apa fancy. public/icons/ Laman Utama » Wire It Up Letakkan layout anda dalam dan keajaiban di dalamnya: PWAProvider import { PWAProvider } from "next-pwa-pack"; export default function layout({ children }) { return <PWAProvider>{children}</PWAProvider>; } Jika anda mahu pengesahan semula untuk bekerja dari sisi pelayan, anda juga perlu mengemas kini middleware anda: // /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*"], }; Pilihan HOC : OriginalMiddleware: middleware asas anda (contohnya, untuk i18n atau auth). revalidationSecret: token rahsia untuk mengunci pengesahan semula cache. sseEndpoint: laluan aliran SSE (sukar jika ia bertentangan). webhookPath: Endpoint to hit untuk memicu pembaharuan cache (diterima oleh revalidatePWA). Di dalam Pembekal Pembekal yang mengumpulkan sekumpulan barang di bawah kapak - dan anda juga boleh memilih komponen cherry-pick: PWAProvider RegisterSW Pihak Berkuasa Perkhidmatan ( Menyelesaikan kesilapan dengan baik.Anda boleh melampaui laluan jika perlu: /sw.js <PWAProvider swPath="/custom/sw.js">{children}</PWAProvider> CacheCurrentPage Menangkap navigasi (termasuk transisi gaya SPA), memadam HTML halaman semasa. SWRevalidateListener Menjaga peristiwa storage lokal dan memicu pembaharuan cache di antara tab. SSERevalidateListener Membaca kepada peristiwa-peristiwa yang dihantar pelayan daripada Apabila backend anda berkata "memvalidasi semula URL ini," pendengar ini memastikan pelanggan melakukannya. sseEndpoint DevPWAStatus Panel Dev-only anda boleh mengaktifkan seperti ini: <PWAProvider devMode>{children}</PWAProvider> Persembahan : Status dalam talian/offline Versi Cache Pembaruan ketersediaan Alat-alat satu klik: bersih cache, unregister SW, menyegarkan, menonaktifkan / mengaktifkan cache Apa yang pekerja perkhidmatan sebenarnya lakukan yang inti Tangan : sw.js HTML dalam caching Pages cached with TTL (default: 10 min - boleh diubahsuai dalam sw.js) Auto-revalidates apabila TTL tamat tempoh Fallback Offline jika HTML hilang aset statik JS, CSS, imej disimpan dalam cache selamanya Hanya Cache Dapatkan Permintaan Mesej Sokongan Menyokong tindakan-tindakan ini daripada pelanggan: CACHE_CURRENT_HTML dalam talian Pengenalan_URL Disable_CACHE / Disable_CACHE / Disable_CACHE Pengangkutan / menunggu CLEAR_STATIC_CACHE dalam talian Fesyen Offline Memberi perkhidmatan offline.html jika rangkaian dan cache kedua-duanya gagal Mencoba untuk menyegarkan apabila kembali dalam talian Menggunakan dalam Middleware Penyerahan Penyerahan Ini ialah di mana Ia membawa pemulihan cache kepada SSR dan Edge Middleware - dengan sokongan SSE dan semua. next-pwa-pack export default withPWA(originalMiddleware, { revalidationSecret: process.env.REVALIDATION_SECRET!, sseEndpoint: "/api/pwa/cache-events", webhookPath: "/api/pwa/revalidate", }); Params: asalMiddleware: logik middleware anda yang sedia ada (auth, i18n, dan lain-lain) revalidationSecret: supaya tidak ada orang lain boleh poke cache anda sseEndpoint: Override jika sesuatu yang lain menggunakan laluan ini webhookPath: digunakan oleh pelayan atau sistem luaran untuk mengesahkan semula URL tertentu Kasus penggunaan dunia sebenar Mengemas kini cache selepas perubahan data import { updateSWCache } from "next-pwa-pack"; // After creating a blog post: const handleCreatePost = async (data) => { await createPost(data); updateSWCache(["/blog", "/dashboard"]); }; Memperbarui cache daripada pelayan import { revalidatePWA } from "../actions"; await createPost(data); await revalidatePWA(["/my-page"]); Membersihkan Cache pada Logout import { clearAllCache } from "next-pwa-pack"; const handleLogout = async () => { await logout(); await clearAllCache(); router.push("/login"); }; Semua Klien Cache Tindakan 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(); Rute API untuk pemicu cache luaran Jika anda ingin memicu pembaharuan cache secara luaran (contohnya, daripada panel pentadbiran), berikut ialah laluan API yang anda boleh gunakan: // 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 }); } } Letakkan ia dengan: POST https://your-app.com/api/webhook/revalidate { "tags": ["faq"], "secret": "1234567890", "urls": ["/ru/question-answer"] } Debugging dan DevTools Berikut ialah apa yang anda boleh semak semasa debugging: Anda boleh pergi ke DevTools → Application → Service Workers. Mengesahkan bahawa pekerja telah didaftarkan. Semak Cache Storage → html-cache-v2 untuk melihat sama ada halaman disimpan dalam cache. Simulasi Offline dalam Rangkaian → Offline dan muat semula. Console logs from the service worker help too: [PWA] Service Worker registered [SW] Cached: /about [SW] Revalidated and updated cache for: /blog Gotchas & Catatan Beberapa perkara yang perlu anda ketahui sebelum anda berlayar: keselamatan PWA memerlukan HTTPS dalam pengeluaran. Hanya permintaan GET yang disemak. Jangan simpan data sensitif. prestasi Paket ini tidak menyentuh baseline prestasi app anda. Ia meningkatkan beban berulang secara signifikan. Konfigurasi TTL ditetapkan dalam sw.js (default: 10 minit). Anda boleh mengecualikan URL daripada caching melalui CACHE_EXCLUDE. manifest.json perlu disesuaikan dengan aplikasi anda. tindakan revalidatePWA boleh diedit - menyesuaikannya mengikut keperluan. withPWA dan PWAProvider kedua-duanya menerima pilihan: export default function PWAProvider({ children, swPath, devMode = false, serverRevalidation = { enabled: true, sseEndpoint: "/api/pwa/cache-events" }, }: PWAProviderProps) { Apa yang seterusnya telah ditulis untuk Ia perlu bekerja pada juga - hanya tidak diuji secara meluas. next-pwa-pack Next.js 15 Next.js 13 App Router Ciri-ciri yang direncanakan : Konfigurasi TTL melalui opsyen (tidak mengedit sw.js) Push pemberitahuan Kawalan Cache Berasaskan Pattern Metrik prestasi untuk kecekapan cache Itulah yang Jika anda bosan dengan bertengkar dengan pekerja perkhidmatan secara manual, berikan Anda akan pergi daripada nol kepada sokongan PWA penuh dalam satu istirahat kopi. next-pwa-pack Soalan, bug, atau maklum balas?Buka masalah atau hubungi kami. 👉 github.com/dev-keluarga/next-pwa-pack
