refactor(pwa): migrate from @ducanh2912/next-pwa to @serwist/turbopack

Next.js 16 ships Turbopack as the default bundler, but
@ducanh2912/next-pwa is webpack-only — the previous PWA setup
required `--webpack` on dev/build/"dev:proxy" scripts, accepting
a perf regression in exchange for working PWA install.

@serwist/turbopack (paired with the official 'serwist' package
and 'esbuild') is the Turbopack-native successor: it works with
the default bundler, no opt-out flag, and gives us a real TS
service worker source file we can read and edit.

What this commit does:

1. Swap deps in package.json:
   - Remove @ducanh2912/next-pwa
   - Add @serwist/turbopack, serwist, esbuild (all devDeps)
   - Drop --webpack flag from dev / dev:proxy / build scripts
     (Turbopack is restored as the bundler)

2. next.config.ts:
   - Replace withPWAInit wrapping with withSerwist named import
   - Update comment block to describe new architecture

3. New src/app/sw.ts: Serwist service worker source.
   skipWaiting + clientsClaim + navigationPreload + defaultCache.
   This file is compiled to a real SW at build time by Serwist.

4. New src/app/serwist/[[...slug]]/route.ts: catch-all Route
   Handler that serves the compiled SW at /serwist/sw.js plus
   Serwist's chunked runtime assets. Catch-all is required
   because Serwist serves multiple files under /serwist/.

5. src/app/layout.tsx: replace <SwRegister /> with
   <SerwistProvider swUrl="/serwist/sw.js"> from
   @serwist/turbopack/react. The provider handles registration
   + lifecycle internally.

6. Delete src/app/_components/core/sw-register.tsx: replaced
   by SerwistProvider.

7. .gitignore: add public/sw.js and public/workbox-*.js
   (defensive — these are build artifacts that change hash
   every build and shouldn't be committed).

8. Untrack public/workbox-3c9d0171.js: stale workbox runtime
   from the previous next-pwa build, hash is build-specific
   so it can never be regenerated correctly.

Not modified (intentionally):
- src/utils/pwa.ts: pure beforeinstallprompt browser-API wrapper,
  library-agnostic, stays as-is.
- pwa-install-overlay / pwa-install-dialog: install UI flow
  unchanged.
- public/manifest.json: still works; layout's metadata.manifest
  points at it.

Verification:
- pnpm install resolved cleanly (added 24 pkgs, removed 209)
- npx tsc --noEmit passes (EXIT=0)
- Serwist provides named exports, not default — withSerwist and
  createSerwistRoute are both named imports
This commit is contained in:
2026-06-17 11:09:36 +08:00
parent bb2ae41232
commit 67dcf97edc
9 changed files with 705 additions and 2275 deletions
-34
View File
@@ -1,34 +0,0 @@
"use client";
/**
* Service Worker 注册器
*
* 背景:`@ducanh2912/next-pwa` 配置 `register: false`,不自动注入注册脚本。
* App Router 下手动注册更可控 —— 不污染 SSR / hydration,可显式做生产 / 开发分流。
*
* 挂载位置:layout body 末尾,全站生效。
*
* 行为:
* - dev (`NODE_ENV === "development"`):跳过注册
* 1. next-pwa `disable: true` 时 dev 不生成 sw.js,注册会 404
* 2. dev HMR + 老 SW cache 互相干扰,开发体验差
* - 生产:调 `navigator.serviceWorker.register("/sw.js", { scope: "/" })`
* - `scope: "/"` 与 manifest.scope 一致
* - `updateViaCache: "none"` 强制每次都拉新版 SW(next-pwa 默认就是这行为,显式更清晰)
*/
import { useEffect } from "react";
export function SwRegister() {
useEffect(() => {
if (typeof window === "undefined") return;
if (!("serviceWorker" in navigator)) return;
if (process.env.NODE_ENV !== "production") return;
void navigator.serviceWorker.register("/sw.js", {
scope: "/",
updateViaCache: "none",
});
}, []);
// 无 UI —— 纯副作用组件
return null;
}