如何使用 Next.js Serwist Thirdweb 嵌入式钱包模板

本指南将带您使用模板,该模板使用 Next.js、Serwist(离线能力) 和 Thirdweb 嵌入式钱包在 Monad 上构建渐进式 Web 应用(PWA)。

前置条件

Node.js(v18 或更高版本)
一个 Thirdweb 账户

设置

克隆仓库:

git clone https://github.com/monad-developers/next-serwist-thirdweb.git

cd 进入项目目录:
cd next-serwist-thirdweb
安装依赖:
npm install
在根目录创建 .env.local 文件:
cp .env.example .env.local

开始向 .env.local 文件添加环境变量:

# Thirdweb Configuration (Required)
NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_thirdweb_client_id_here

# Web Push (Required)
WEB_PUSH_EMAIL=user@example.com
WEB_PUSH_PRIVATE_KEY=your_vapid_private_key
NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY=your_vapid_public_key

如果您丢失了 Thirdweb Client ID,可以在 Thirdweb 仪表盘中找到。

为 Web 推送通知生成 VAPID 密钥:
npx web-push generate-vapid-keys --json
将生成的密钥复制到您的 .env.local 文件中(替换步骤 5 中的占位值)。
运行应用: 开发模式:
npm run dev
应用将在 http://localhost:3000 上可用。 生产模式: 完整的 PWA 功能(包括安装提示):
npm run build && npm run start

模板文件夹结构

next-serwist-thirdweb/
├── app/
│   ├── components/         # React components
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   └── ...
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
└── ...

更改应用名称

Edit public/manifest.json:
- 修改 name 和 short_name 字段
运行 npm run build 更新应用

通知设置

要接收此应用的推送通知,您需要在浏览器和/或系统设置中启用通知。

浏览器设置

Chrome/Edge

点击地址栏中的锁形图标 🔒
将 “Notifications” 设置为 “Allow”
或前往 Settings → Privacy and security → Site Settings → Notifications

Firefox

点击地址栏中的盾牌图标 🛡️
如有需要,为此站点关闭 “Enhanced Tracking Protection”
在出现提示时允许通知
或前往 Settings → Privacy & Security → Permissions → Notifications

Safari

前往 Safari → Settings → Websites → Notifications
找到您的站点并将其设置为 “Allow”

系统设置

macOS

System Preferences → Notifications & Focus
找到您的浏览器并确保通知已启用
在浏览器设置中勾选 “Allow notifications from websites”

Windows

Settings → System → Notifications & actions
确保您的浏览器可以发送通知
检查浏览器通知设置

iOS

Settings → Notifications → [您的浏览器]
启用 “Allow Notifications”
同时在浏览器设置中启用

Android

Settings → Apps → [您的浏览器] → Notifications
启用通知
检查浏览器通知权限

需要后端集成

SendNotification.tsx 需要后端实现:

在用户订阅时 保存订阅数据(参见代码中的 TODO 注释)
在用户取消订阅时 删除订阅数据
实现 /notification 端点 以发送实际的推送通知
使用 web-push 库 或类似方案进行服务器端通知投递

自定义通知内容

要自定义推送通知内容,请编辑 app/notification/route.ts ,并修改 sendNotification 调用中的 title、message、icon 及其他属性。

修改应用图标和启动画面

应用图标

将 public/icons/ 目录下的图标文件替换为您的自定义图标:

icon-512x512.png - 主应用图标(512×512px)
android-chrome-192x192.png - Android 图标(192×192px)
apple-touch-icon.png - iOS 主屏幕图标(180×180px)

同时更新 favicon:

public/favicon.ico - 浏览器 favicon
app/favicon.ico - Next.js 应用 favicon

启动画面

启动画面根据您的应用图标和在以下位置定义的主题颜色自动生成: public/manifest.json。要自定义:

在以下位置更新 theme_color 和 background_color: public/manifest.json
确保您的主图标(icon-512x512.png)代表您的品牌
运行 npm run build 以应用更改

使用 PWA Asset Generator 等工具从单张源图片生成所有所需的图标尺寸。

部署到 Vercel

使用 Vercel 仪表盘

连接您的仓库:
- 将您的代码推送到 GitHub
- 访问 vercel.com 并导入您的仓库
配置环境变量:
- 在您的 Vercel 项目仪表盘,前往 Settings → Environment Variables
- 添加与您的 .env.local 相同的变量:
  NEXT_PUBLIC_THIRDWEB_CLIENT_ID WEB_PUSH_EMAIL WEB_PUSH_PRIVATE_KEY NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
部署:Vercel 将自动构建并部署您的应用
更新 Thirdweb 设置:在您的 Thirdweb 仪表盘中,将您的 Vercel 域名(例如 your-app.vercel.app)添加到允许的来源

PWA 功能(安装提示、离线支持、推送通知)会在 HTTPS 域名上(如 Vercel 部署)自动生效。

使用 Vercel CLI

或者,使用 Vercel CLI 部署:

安装 Vercel CLI:
npm i -g vercel
登录 Vercel:
vercel login
部署:
vercel
按照提示配置您的项目。

添加环境变量:

vercel env add NEXT_PUBLIC_THIRDWEB_CLIENT_ID
vercel env add WEB_PUSH_EMAIL
vercel env add WEB_PUSH_PRIVATE_KEY
vercel env add NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY

您也可以前往 Vercel 仪表盘在那里添加环境变量。

使用环境变量重新部署:
vercel --prod

简介

开发者要点

工具和基础设施

JSON-RPC

指南

资源

面向 AI 智能体

如何使用 Next.js Serwist Thirdweb 嵌入式钱包模板

前置条件

设置

模板文件夹结构

更改应用名称

通知设置

浏览器设置

系统设置

需要后端集成

自定义通知内容

修改应用图标和启动画面

应用图标

启动画面

部署到 Vercel

使用 Vercel 仪表盘

使用 Vercel CLI

了解更多

​前置条件

​设置

​模板文件夹结构

​更改应用名称

​通知设置

​浏览器设置

​系统设置

​需要后端集成

​自定义通知内容

​修改应用图标和启动画面

​应用图标

​启动画面

​部署到 Vercel

​使用 Vercel 仪表盘

​使用 Vercel CLI

​了解更多

前置条件

设置

模板文件夹结构

更改应用名称

通知设置

浏览器设置

系统设置

需要后端集成

自定义通知内容

修改应用图标和启动画面

应用图标

启动画面

部署到 Vercel

使用 Vercel 仪表盘

使用 Vercel CLI

了解更多