Add PWA: installable app (Serwist)

You turn the current project's Next.js app into a PWA: installable on the home screen, launchable in full screen, with a service worker that serves a fallback offline cache. You also add a small window that invites the user to install the app and explains how to do it on mobile.

Communication

• Detect the user's language from the conversation (the user's own messages, anywhere in the session - not just this invocation: a bare slash command like /bootstrap carries no language signal by itself). If nothing in the conversation gives a signal, fall back to the OS locale (node -e "console.log(Intl.DateTimeFormat().resolvedOptions().locale)") before defaulting to English. ALWAYS reply in that language for every user-facing message: questions, progress, confirmations, summaries, errors - including any example text quoted in this skill, which is illustrative and must be translated, never sent verbatim.
• Use plain, non-technical business language. Never expose internal script names (*.mjs) or jargon; describe actions in human terms.
• When generating user-facing content for the scaffolded project (UI labels, emails, copy), write it in the user's language too.
• Show progress as a short natural-language checklist (in-progress and done states).

Step 0: Re-run? (idempotence)

Detect whether the PWA is already in place: the hypervibe:pwa marker at the top of <WEB_DIR>/src/app/manifest.ts.

test -f "<WEB_DIR>/src/app/manifest.ts" && grep -q "hypervibe:pwa" "<WEB_DIR>/src/app/manifest.ts" && echo present || echo absent

• absent → initial installation, continue to Step 1.
• present → show a menu: (1) regenerate the icons, (2) change the manifest name / colors, (3) reinstall the service worker, (4) reinstall the install window, (5) redo everything. Only handle what is requested, then jump to the summary.

Step 1: Prerequisites

1. Detect project root: invoke _detect-project-root → WEB_DIR, IS_MONOREPO, PROJECT_NAME, IS_NEXTJS. Abort if not Next.js (the PWA relies on Next's App Router).
2. Favicon source: check that <WEB_DIR>/src/app/icon.svg exists (generated by /bootstrap). If it is missing, create it first (rounded square with the project initial, palette from globals.css) or ask for a square logo, since the PWA icons derive from it.

The path to the templates and scripts: ${CLAUDE_SKILL_DIR}/../../templates/pwa/ and ${CLAUDE_SKILL_DIR}/../../scripts/.

Step 2: Install Serwist

pnpm add @serwist/next serwist
pnpm add -D sharp

(sharp is only used to generate the icons in Step 4, it is a dev dependency.)

⚠️ With pnpm 10, installing sharp may show Ignored build scripts: sharp: this is harmless (the precompiled binaries come through optional dependencies, the build script is just a fallback). Do not run pnpm approve-builds, do not try to "fix" it: verified in real conditions, sharp works as is.

Step 3: Manifest

1. Copy templates/pwa/manifest.ts to <WEB_DIR>/src/app/manifest.ts (Next then serves /manifest.webmanifest and automatically injects <link rel="manifest">).
2. Replace the placeholders based on the project context:
   • __APP_NAME__ / __SHORT_NAME__: from the project's CLAUDE.md or package.json. Keep the short name short (12 chars max, display constraint under the icon).
   • __APP_DESCRIPTION__: one sentence.
   • __THEME_COLOR__ / __BG_COLOR__: read the background and accent color from globals.css (palette variables). The theme_color colors the status bar once installed.
   • __LANG__: the project's default locale (fr usually; read i18n/routing.ts if i18n).
3. Do NOT remove the // hypervibe:pwa comment (it is the marker that /add-push-notification detects).

Step 4: Service worker (Serwist) + icons

4a. Service worker

1. Copy templates/pwa/sw-base.ts to <WEB_DIR>/src/app/sw.ts (minimal offline cache: NetworkFirst, fresh content as soon as there is network, offline fallback otherwise). Keep the // hypervibe:push-handlers marker (insertion point for /add-push-notification).
2. Wrap the Next config with Serwist. Read <WEB_DIR>/next.config.* and add at the top:

   import withSerwistInit from "@serwist/next";
   const withSerwist = withSerwistInit({
     swSrc: "src/app/sw.ts",
     swDest: "public/sw.js",
     disable: process.env.NODE_ENV === "development", // évite les soucis de cache en dev
   });

   and export withSerwist(config) instead of config (adapt to the existing form of the file, CJS or ESM).
3. Add the SW's generated artifacts to .gitignore:

   public/sw.js
   public/swe-worker-*.js

4. Exclude the generated SW from the tsconfig (CRITICAL, verified in real conditions): the T3 tsconfig has checkJs: true, so without this exclusion the next build fails while typechecking the minified public/sw.js ("implicitly has type 'any'"). In tsconfig.json, add to exclude:

   "exclude": ["node_modules", "generated", "public/sw.js", "public/swe-worker-*.js"]

   (merge with the existing entries, do not replace them).

4b. Icons

Generate the manifest PNGs from the SVG favicon, with the theme's background color. Mandatory: run with the cwd at the project root (cd "<WEB_DIR>"), because the script resolves sharp from the current project:

cd "<WEB_DIR>" && node "${CLAUDE_SKILL_DIR}/../../scripts/generate-pwa-icons.mjs" \
  --svg "<WEB_DIR>/src/app/icon.svg" --out "<WEB_DIR>/public/icons" --bg "<THEME_COLOR_HEX>"

--bg expects a hex (#RRGGBB): if the globals.css palette is in oklch()/hsl(), convert the color to hex before the call. Produces icon-192.png, icon-512.png, icon-maskable-512.png (solid background + safe zone) and apple-touch-icon.png.

Step 5: iOS meta + install window

1. Copy templates/pwa/ios-share-icon.tsx and templates/pwa/install-prompt.tsx to <WEB_DIR>/src/components/.
2. In install-prompt.tsx: replace __APP_NAME__ and __LOGO_LETTER__ (project initial), and adapt the color classes (bg-foreground/bg-background/border-border) to the actual palette if the tokens differ (read globals.css).
3. Mount <InstallPrompt /> in the root layout (<WEB_DIR>/src/app/layout.tsx, or [locale]/layout.tsx if i18n), just before </body>.
4. iOS meta in the root layout's metadata / viewport (Next 15):

   export const metadata: Metadata = {
     // ...existant...
     appleWebApp: { capable: true, statusBarStyle: "default", title: "<SHORT_NAME>" },
     icons: { apple: "/icons/apple-touch-icon.png" },
   };
   export const viewport: Viewport = { themeColor: "<THEME_COLOR_HEX>" };

   (Merge with an existing metadata/viewport rather than duplicating it.)

The window only shows on mobile/tablet, not if the app is already installed, and reappears 3 days after a "Later".

Step 6: CLAUDE.md

Invoke _update-claude-md with:

• stack: - **PWA** : Serwist (service worker, manifest, installable) ; icônes dans \public/icons/``
• conventions: - PWA : le service worker est \src/app/sw.ts` (compilé en `public/sw.js` au build, désactivé en dev). Pour ajouter des notifications push, lancer `/add-push-notification` (qui étend ce service worker).`

Step 7: Verification + summary

cd "<WEB_DIR>" && pnpm tsc --noEmit && pnpm lint

Never run pnpm build or the dev server to "see" the PWA. The service worker is only active in build/prod (disabled in dev); installability is verified after deployment.

Summary for the user:

• The app is now installable (home screen, full screen).
• A window invites installation on mobile (native button on Android, "Add to Home Screen" instructions on iOS).
• Minimal offline cache in place.
• To test after deployment: open the site on mobile, check the invitation and installation.
• Possible next step: /add-push-notification to send push notifications (needs this PWA).