How to use the Next.js Serwist Thirdweb embedded wallet template

This guide walks you through using the template which uses Next.js, Serwist (offline capabilities), and Thirdweb embedded wallet to build a Progressive Web Application (PWA) on Monad.

Prerequisites

• Node.js (v18 or higher)
• a Thirdweb account

Setup

1. Clone the repository:

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

2. cd into the project directory:

   cd next-serwist-thirdweb

3. Install dependencies:

   npm install

4. Create a .env.local file in the root directory:

   cp .env.example .env.local

5. Start adding your environment variables to the .env.local file:

   # 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

   If you lost your Thirdweb Client ID, you can find it in the Thirdweb dashboard.

6. Generate VAPID keys for web push notifications:

   npx web-push generate-vapid-keys --json

   Copy the generated keys to your .env.local file (replace the placeholder values from step 5).

7. Running the Application:

   Development Mode:

   npm run dev

   The application will be available at http://localhost:3000.

   Production Mode:

   For full PWA functionality (including install prompts):

   npm run build && npm run start

Folder structure of the template

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

Changing the app name

• Edit public/manifest.json:
  • Change the name and short_name fields
• Run npm run build to update the app

Notification Setup

Enable notifications for the best experience!

To receive push notifications from this app, you need to enable notifications in your browser and/or system settings.

Browser Settings

Chrome/Edge

1. Click the lock icon 🔒 in the address bar
2. Set "Notifications" to "Allow"
3. Or go to Settings → Privacy and security → Site Settings → Notifications

Firefox

1. Click the shield icon 🛡️ in the address bar
2. Turn off "Enhanced Tracking Protection" for this site (if needed)
3. Allow notifications when prompted
4. Or go to Settings → Privacy & Security → Permissions → Notifications

Safari

1. Go to Safari → Settings → Websites → Notifications
2. Find your site and set it to "Allow"

System Settings

macOS

1. System Preferences → Notifications & Focus
2. Find your browser and ensure notifications are enabled
3. Check "Allow notifications from websites" in browser settings

Windows

1. Settings → System → Notifications & actions
2. Ensure your browser can send notifications
3. Check browser notification settings

iOS

1. Settings → Notifications → [Your Browser]
2. Enable "Allow Notifications"
3. Also enable in browser settings

Android

1. Settings → Apps → [Your Browser] → Notifications
2. Enable notifications
3. Check browser notification permissions

Backend Integration Required

The SendNotification.tsx component is sample code

SendNotification.tsx requires backend implementation:

• Save subscription data when users subscribe (see TODO comments in code)
• Delete subscription data when users unsubscribe
• Implement /notification endpoint to send actual push notifications
• Use web-push library or similar for server-side notification delivery

Customizing Notification Content

To customize your push notification content, edit app/notification/route.ts and modify the title, message, icon, and other properties in the sendNotification call.

Modifying the App Icon & Splash Screen

App Icons

Replace the icon files in the public/icons/ directory with your custom icons:

• icon-512x512.png - Main app icon (512×512px)
• android-chrome-192x192.png - Android icon (192×192px)
• apple-touch-icon.png - iOS home screen icon (180×180px)

Also update the favicon:

• public/favicon.ico - Browser favicon
• app/favicon.ico - Next.js app favicon

Splash Screen

Splash screens are automatically generated from your app icon and theme colors defined in public/manifest.json. To customize:

1. Update the theme_color and background_color in public/manifest.json
2. Ensure your main icon (icon-512x512.png) represents your brand
3. Run npm run build to apply changes

tip

Use tools like PWA Asset Generator to create all required icon sizes from a single source image.

Deploying to Vercel

Using Vercel Dashboard

1. Connect your repository:

   • Push your code to GitHub
   • Visit vercel.com and import your repository

2. Configure environment variables:

   • In your Vercel project dashboard, go to Settings → Environment Variables
   • Add the same variables from your .env.local:

     NEXT_PUBLIC_THIRDWEB_CLIENT_ID
     WEB_PUSH_EMAIL
     WEB_PUSH_PRIVATE_KEY
     NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY

3. Deploy: Vercel will automatically build and deploy your app

4. Update Thirdweb settings: In your Thirdweb dashboard, add your Vercel domain (e.g., your-app.vercel.app) to the allowed origins

tip

PWA features (install prompts, offline support, push notifications) work automatically on HTTPS domains like Vercel deployments.

Using Vercel CLI

Alternatively, deploy using the Vercel CLI:

1. Install Vercel CLI:

   npm i -g vercel

2. Login to Vercel:

   vercel login

3. Deploy:

   vercel

   Follow the prompts to configure your project.

4. Add environment variables:

   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

   Or you can go to the Vercel dashboard and add the environment variables there.

5. Redeploy with environment variables:

   vercel --prod

Learn more

• Serwist: docs | guides
• Thirdweb: docs | guides
• Monad: supported tooling and infra