pwa-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PWA Development

PWA开发

Implement Progressive Web App features including service workers, caching strategies, offline support, and installation prompts for React and Svelte applications.

为React和Svelte应用实现渐进式Web应用（PWA）功能，包括Service Worker、缓存策略、离线支持和安装提示。

When to Use This Skill

使用场景

Use this skill when:

Adding PWA capabilities to a web app
Implementing offline support
Creating service worker caching strategies
Debugging PWA installation issues
Handling iOS-specific PWA quirks

Do NOT use this skill when:

Building backend APIs
Working on requirements/design (use those skills first)
Need complex offline-first architecture (design first)

在以下场景使用此技能：

为Web应用添加PWA功能
实现离线支持
制定Service Worker缓存策略
调试PWA安装问题
处理iOS平台特有的PWA兼容性问题

请勿在以下场景使用此技能：

构建后端API
处理需求/设计工作（请先使用对应技能）
需要复杂的离线优先架构（先进行设计）

Core Principle

核心原则

PWAs fail when offline behavior is an afterthought. A PWA is not "add service worker to existing app." It's a fundamental architectural decision about data flow, caching, and connectivity failure.

如果离线功能是事后添加的，PWA必然失败。 PWA不是“在现有应用中添加Service Worker”这么简单，而是关于数据流、缓存和连接故障处理的根本性架构决策。

Diagnostic States

诊断状态

P0: No PWA Setup

P0：未配置PWA

Symptoms: No manifest.json, no service worker, online-only

Interventions:

Run
```
scripts/manifest-generator.ts
```
to create manifest
Add
```
<link rel="manifest">
```
to HTML head
Generate minimal SW with
```
scripts/sw-scaffolder.ts
```

症状： 无manifest.json文件，无Service Worker，仅支持在线访问

解决方案：

运行
```
scripts/manifest-generator.ts
```
生成manifest文件
在HTML头部添加
```
<link rel="manifest">
```
标签
使用
```
scripts/sw-scaffolder.ts
```
生成基础的Service Worker

P1: Basic Manifest Only

P1：仅配置基础Manifest

Symptoms: Manifest exists but SW missing, breaks offline

Key Questions:

What content MUST be available offline?
What should always be fresh (network-first)?

Interventions:

Use
```
scripts/cache-strategy-advisor.ts
```
Implement app shell pattern
Add offline fallback page

症状： 存在Manifest文件但缺少Service Worker，离线时无法正常工作

关键问题：

哪些内容必须支持离线访问？
哪些内容需要始终保持最新（网络优先）？

解决方案：

使用
```
scripts/cache-strategy-advisor.ts
```
工具
实现应用壳（App Shell）模式
添加离线备用页面

P2: Caching Issues

P2：缓存问题

Symptoms: Stale content, unexpected caching behavior

Interventions:

Audit with
```
scripts/pwa-audit.ts
```
Map resources to strategies using
```
data/caching-strategies.json
```
Add cache expiration and cleanup

症状： 内容过期，缓存行为不符合预期

解决方案：

运行
```
scripts/pwa-audit.ts
```
进行审计
参考
```
data/caching-strategies.json
```
为资源匹配对应策略
添加缓存过期和清理机制

P3: Update Problems

P3：更新问题

Symptoms: Users stuck on old versions, multiple refreshes needed

Interventions:

Implement skipWaiting/clients.claim appropriately
Add update notification UI (
```
assets/update-prompt.tsx
```
)
Handle "waiting" state properly

症状： 用户停留在旧版本，需要多次刷新才能更新

解决方案：

合理实现skipWaiting/clients.claim功能
添加更新通知UI（
```
assets/update-prompt.tsx
```
）
正确处理“等待更新”状态

P4: Offline Data Gaps

P4：离线数据缺口

Symptoms: User actions lost offline, no sync indicator

Interventions:

Implement IndexedDB for offline storage
Add Background Sync API
Create sync status UI

症状： 用户在离线时的操作丢失，无同步状态提示

解决方案：

采用IndexedDB实现离线存储
集成Background Sync API
开发同步状态UI

P5: iOS Issues

P5：iOS兼容性问题

Symptoms: Works on Android, breaks on iOS

Interventions:

Review
```
data/ios-quirks.json
```
Add apple-mobile-web-app meta tags
Handle storage eviction gracefully

症状： 在Android上正常工作，在iOS上出现故障

解决方案：

查阅
```
data/ios-quirks.json
```
文档
添加apple-mobile-web-app元标签
优雅处理存储回收问题

P6: Production Ready

P6：生产就绪

Indicators: Lighthouse PWA 100, works offline, updates cleanly

指标： Lighthouse PWA评分100，离线可正常使用，更新流程顺畅

Caching Strategies

缓存策略

Strategy	Use For	Behavior
Cache First	Static assets, fonts	Serve from cache, update in background
Network First	API data, user content	Try network, fall back to cache
Stale While Revalidate	Semi-static content	Serve stale, update cache for next time
Network Only	Auth, real-time data	Always network, no caching

策略	适用场景	行为
Cache First	静态资源、字体	从缓存加载，后台更新
Network First	API数据、用户内容	优先尝试网络请求，失败时 fallback 到缓存
Stale While Revalidate	半静态内容	先返回缓存的旧内容，后台更新缓存供下次使用
Network Only	认证接口、实时数据	仅通过网络请求，不进行缓存

Available Scripts

可用脚本

Script	Purpose
`manifest-generator.ts`	Generate manifest.json
`sw-scaffolder.ts`	Generate service worker
`cache-strategy-advisor.ts`	Recommend caching strategies
`pwa-audit.ts`	Validate PWA configuration

脚本	用途
`manifest-generator.ts`	生成manifest.json文件
`sw-scaffolder.ts`	生成Service Worker
`cache-strategy-advisor.ts`	推荐缓存策略
`pwa-audit.ts`	验证PWA配置

Anti-Patterns

反模式

The Everything Cache

全量缓存

Precaching every asset - massive initial download. Fix: Precache only critical app shell. Runtime cache content.

预缓存所有资源 - 初始下载体积过大。 修复方案： 仅预缓存关键的应用壳资源，运行时再缓存其他内容。

The Immortal Cache

永久缓存

Never expiring caches - stale content forever. Fix: Cache versioning, delete old on activate, set max age.

缓存永不过期 - 内容永远处于过期状态。 修复方案： 为缓存添加版本标识，在激活时删除旧缓存，设置最大有效期。

The Silent Update

静默更新

Forcing updates without notification. Fix: Notify user, let them choose when to refresh.

强制更新而不通知用户。 修复方案： 通知用户更新，让用户选择刷新时机。

The iOS Afterthought

忽视iOS

Building for Chrome, testing iOS last. Fix: Test iOS early. Accept iOS limitations.

先为Chrome开发，最后才测试iOS。 修复方案： 尽早测试iOS，接受iOS的平台限制。

Framework Quick Reference

框架快速参考

React + Vite

bash

npm i -D vite-plugin-pwa

bash

npm i -D vite-plugin-pwa

SvelteKit

bash

npm i -D @vite-pwa/sveltekit

bash

npm i -D @vite-pwa/sveltekit

Next.js

bash

npm i next-pwa

See

data/framework-patterns.json

for configuration.

bash

npm i next-pwa

配置详情请查看

data/framework-patterns.json

。

Debugging Checklist

调试检查清单

DevTools > Application > Manifest - Valid?
DevTools > Application > Service Workers - Registered?
DevTools > Application > Cache Storage - What's cached?
DevTools > Network > Offline - Works offline?
Lighthouse > PWA - Score and failures?
iOS Safari - Test on actual device

开发者工具 > 应用 > Manifest - 配置是否有效？
开发者工具 > 应用 > Service Workers - 是否已注册？
开发者工具 > 应用 > 缓存存储 - 缓存了哪些内容？
开发者工具 > 网络 > 离线 - 离线时能否正常工作？
Lighthouse > PWA - 评分及失败项？
iOS Safari - 在真实设备上测试

pwa-development

Original

Translation

PWA Development

PWA开发

When to Use This Skill

使用场景

Core Principle

核心原则

Diagnostic States

诊断状态

P0: No PWA Setup

P0：未配置PWA

P1: Basic Manifest Only

P1：仅配置基础Manifest

P2: Caching Issues

P2：缓存问题

P3: Update Problems

P3：更新问题

P4: Offline Data Gaps

P4：离线数据缺口

P5: iOS Issues

P5：iOS兼容性问题

P6: Production Ready

P6：生产就绪

Caching Strategies

缓存策略

Available Scripts

可用脚本

Anti-Patterns

反模式

The Everything Cache

全量缓存

The Immortal Cache

永久缓存

The Silent Update

静默更新

The iOS Afterthought

忽视iOS

Framework Quick Reference

框架快速参考

React + Vite

React + Vite

SvelteKit

SvelteKit

Next.js

Next.js

Debugging Checklist

调试检查清单

Related Skills

相关技能