Rád vytvářím nástroje, které nejen fungují – jsou Můj tým byl v trencích Next.js dostatečně dlouho, aby přesně věděl, co bolí. - drop-in balíček, který napojí plnou podporu PWA ve vaší aplikaci Next.js, aniž byste si roztrhli vlasy. Vyjděte ze své cesty next-pwa-pack The Backstory (aka: Proč jsem napsal tuto věc) Pokaždé, když se klient zmínil o „podpoře PWA“, objímal jsem se. Zkoušel jsem stávající knihovny. Příliš mnoho magie. Tuny konfig. Nebo prostě zcela neslučitelné s - který, mimochodem, jsme plně přijali. chtěl jsem: App Router Obnovení serverové cache. Integrace s routerem. Snadná synchronizace mezi kartami. Čistý API pro správu vyrovnávací paměti z backend. Místo toho jsem skončil psaním servisních pracovníků ručně. Tuning cache TTLs. Řešení aktualizace logiky. Správa stálých klientů. Ruční vymazání cache pokaždé, když jsme odeslali. A ani mě nezačínejte na uživatelích, kteří nevidí aktualizace, dokud se neosvěží. Potřeboval jsem něco jednoduchého, předvídatelného a bojově testovaného. Budova Co se do ní dostalo Příští balíček Příští balíček Prvním krokem bylo napsat pracovníka minimálních služeb: Cache HTML s TTL. Řídí statické aktiva. Funguje offline, jako by měla být skutečná PWA. Poté jsem přidal systém pro zasílání zpráv, aby klient mohl mluvit se servisním pracovníkem - například, aby rozbil vyrovnávací paměť nebo zcela zakázal vyrovnávací paměť. Následně jsem napsal několik scénářů: Automaticky zkopírujte sw.js, manifest.json a offline.html do projektu. Vložte serverovou akci s názvem revalidatePWA, kterou můžete použít kdekoli (API trasy, serverové akce, serverové komponenty – vyberte si). Pro plnou podporu App Router a SSR / Edge jsem vše zabaleno do funkce vyššího řádu: Jeden import, jeden hovor – hotovo. withPWA Také jsem vytvořil synchronizaci karty. protože uživatelé otevřete svou aplikaci ve 3 kartách a očekávejte, že budou magicky aktualizovány v synchronizaci. + více k událostem . Willová localStorage storage Výsledek? balíček, který prostě funguje. Žádná konfigurace černé magie. Žádné přepisování základních částí vaší aplikace. Co získáte s Příští balíček Příští balíček Jakmile je nainstalován, získáte: Registrace servisního pracovníka z krabice - bez kotle. Offline backup s přizpůsobitelným offline.html. Automaticky kopírované soubory, které můžete upravit (manifest, SW atd.). API pro řízení vyrovnávací paměti – jasné, aktualizované, vypnuté, vše programově. Synchronizace mezi kartami – žádný stálý obsah v nastavení více karet. Dev panel pro stav PWA v reálném čase během lokálního vývoje. Podpora obnovení validace na straně serveru prostřednictvím akcí serveru, tras API nebo externích integrací webhook. Balíček si můžete stáhnout zde: https://github.com/dev-family/next-pwa-pack Co se stane, když ho nainstalujete Instalační skript automaticky kopíruje PWA boilerplate do : /public sw.js – váš servisní pracovník s cache logikou. offline.html – zpětná stránka pro režim offline. manifest.json – upravte ji tak, aby vyhovovala vaší aplikaci. ⚠️ Stávající soubory nebudou přepsány - respektuje vaše nastavení. Pokud chcete kopii spustit ručně: node node_modules/next-pwa-pack/scripts/copy-pwa-files.mjs # or npx next-pwa-pack/scripts/copy-pwa-files.mjs Akce serveru Je také přidán do vašeho nebo Soubor v závislosti na vaší složce: 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(); } Pokud se tento soubor nezobrazí, můžete spustit: node node_modules/next-pwa-pack/scripts/copy-pwa-server-actions.mjs Konfigurace vašeho manifest.json Prohlášení - Jason Po instalaci nezapomeňte přizpůsobit : /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" } ] } Vložte své ikony do Nebo se podívejte na výše uvedené trasy.Nic fantastické. public/icons/ Rychlý start: Wire It Up Vložte svůj layout do Kouzelné kouzlo se šíří v: PWAProvider import { PWAProvider } from "next-pwa-pack"; export default function layout({ children }) { return <PWAProvider>{children}</PWAProvider>; } Pokud chcete, aby revitalizace fungovala ze strany serveru, budete také muset aktualizovat svůj middleware: // /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*"], }; Možnosti pro HOC: originálníMiddleware: váš základní middleware (např. pro i18n nebo auth). revalidationSecret: tajný token pro uzamčení revalidace cache. sseEndpoint: SSE stream path (změna, pokud je v rozporu). webhookPath: Endpoint to hit pro spuštění obnovení vyrovnávací paměti (používá revalidatePWA). Uvnitř PWP poskytovatel PWP poskytovatel Tyto balíček spoustu věcí pod kapotou - a můžete cherry-pick komponenty taky: PWAProvider RegisterSW automaticky zaregistruje pracovníka služby ( Můžete překonat cestu, pokud je to nutné: /sw.js <PWAProvider swPath="/custom/sw.js">{children}</PWAProvider> CacheCurrentPage Interceptuje navigaci (včetně přechodů ve stylu SPA), vyrovnává HTML aktuální stránky. SWRevalidateListener Hodinky pro lokalStorage události a spouští obnovení vyrovnávací paměti přes karty. SSERevalidateListener Zobrazuje události odesílané serverem z Když váš backend řekne "přehodnotit tyto adresy URL", tento posluchač zajistí, že klienti to udělají. sseEndpoint DevPWAStatus Dev-only panel můžete povolit takto: <PWAProvider devMode>{children}</PWAProvider> představení : Online / Offline stav Cache verze Aktualizace dostupnosti Jednorázové nástroje: clear cache, unregister SW, refresh, disable/enable cache Co zaměstnanec ve skutečnosti dělá Jádro Ručník : sw.js HTML caching Stránky uložené v mezipaměti pomocí TTL (default: 10 min — tweakable in sw.js) Auto-revaliduje, když TTL vyprší Offline Fallback, pokud chybí HTML Statické aktiva JS, CSS, obrázky jsou vyrovnávány navždy Pouze cache GET žádosti Poselství podpory Podporuje tyto akce od klienta: CACHE_CURRENT_HTML Příslušenství Přihláška_URL Disable_Cache / Disable_Cache / Disable_Cache / Disable_Cache Plavba - čekání CLEAR_STATIC_CACHE Příslušenství Offline móda Slouží offline.html, pokud síť a vyrovnávací paměť selžou Snaží se osvěžit, když se vrátí online Používání ve středověku sběratelská sběratelská To je místo, kde Přináší revalidaci cache do SSR a Edge Middleware – s podporou SSE a vším. next-pwa-pack export default withPWA(originalMiddleware, { revalidationSecret: process.env.REVALIDATION_SECRET!, sseEndpoint: "/api/pwa/cache-events", webhookPath: "/api/pwa/revalidate", }); Params: originálníMiddleware: vaše stávající middleware logika (auth, i18n, atd.) revalidationSecret: takže nikdo jiný nemůže pokynout vaši cache sseEndpoint: přepnout, pokud tuto trasu používá něco jiného webhookPath: používá server nebo externí systémy k opětovnému ověření konkrétních adres URL Případy reálného světa Aktualizace cache po změně dat import { updateSWCache } from "next-pwa-pack"; // After creating a blog post: const handleCreatePost = async (data) => { await createPost(data); updateSWCache(["/blog", "/dashboard"]); }; Aktualizace cache ze serveru import { revalidatePWA } from "../actions"; await createPost(data); await revalidatePWA(["/my-page"]); Čištění cache na Logout import { clearAllCache } from "next-pwa-pack"; const handleLogout = async () => { await logout(); await clearAllCache(); router.push("/login"); }; Všechny klientské cache akce 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 Route pro externí spouštěče cache Pokud chcete spustit aktualizace cache externě (např. z admin panelu), zde je cesta API, kterou můžete použít: // 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 }); } } Dotkněte se ho s: POST https://your-app.com/api/webhook/revalidate { "tags": ["faq"], "secret": "1234567890", "urls": ["/ru/question-answer"] } Debugování & DevTools Zde je to, co můžete zkontrolovat při debugování: Přejděte na DevTools → Application → Service Workers. Potvrďte, že je zaměstnanec registrován. Zkontrolujte úložiště cache → html-cache-v2 a zjistěte, zda jsou stránky cache. Simulujte offline v síti → Offline a přeložte. Console logs from the service worker help too: [PWA] Service Worker registered [SW] Cached: /about [SW] Revalidated and updated cache for: /blog Gotchas & poznámky Několik věcí, které byste měli vědět, než se vydáte na loď: bezpečnosti PWA vyžaduje HTTPS ve výrobě. Pouze požadavky GET jsou vyrovnávány. Neskrývejte citlivá data. Výkonnost Balíček se nedotýká výkonnostní základny vaší aplikace. Výrazně zlepšuje opakované zatížení. Konfigurace TTL je nastaven ve formátu sw.js (default: 10 minut). URL můžete vyloučit z vyrovnávací paměti prostřednictvím CACHE_EXCLUDE. manifest.json musí být přizpůsoben vaší aplikaci. Akce revalidatePWA je editovatelná – přizpůsobte ji podle potřeby. withPWA a PWAProvider obě akceptují možnosti: export default function PWAProvider({ children, swPath, devMode = false, serverRevalidation = { enabled: true, sseEndpoint: "/api/pwa/cache-events" }, }: PWAProviderProps) { Co je následující Je psáno pro Měla by pracovat na Stejně tak, i když nebyla dostatečně testována. next-pwa-pack Next.js 15 Next.js 13 App Router Plánované funkce : Konfigurace TTL prostřednictvím možností (bez úprav sw.js) Push oznámení Kontrola cache založená na vzorcích Metriky výkonu pro efektivitu cache To je to. Jestliže jste unaveni z manuálního hádání servisních pracovníků, dejte Budete jít od nuly k plné podpoře PWA v jedné přestávce. next-pwa-pack Otázky, chyby nebo zpětná vazba?Otevřete problém nebo nás vytočte. 👉👉 github.com/dev-rodič/next-pwa-pack
