Complete Guide: Push Notifications in Next.js

Learn how to add push notifications to your Next.js application that work even when the browser is closed. This guide will walk you through every step with clear explanations.

What You'll Build

By the end of this guide, you'll have:

🔔 Push notifications that work when your app is closed
📱 A non-intrusive notification banner
💾 Persistent user preferences with localStorage
🔒 Secure VAPID authentication
📊 A database to store user subscriptions

Prerequisites

Before starting, make sure you have:

Basic knowledge of React and Next.js
A Next.js 13+ project with App Router
Node.js and npm installed
A database setup (we'll use Prisma with PostgreSQL)

How Push Notifications Work

┌─────────────┐      ┌──────────────┐      ┌──────────────┐
│   Browser   │─────▶│  Your Server │─────▶│   Browser   │
│  (User A)   │      │              │      │  (User B)    │
│             │      │  Stores      │      │              │
│  Subscribes │      │  subscription│      │  Receives    │
│  to push    │      │  & sends     │      │  notification│
│             │      │  notifications│     │              │
└─────────────┘      └──────────────┘      └──────────────┘

Key Components:

Service Worker - Runs in the background, receives notifications
Push API - Allows your server to send notifications
VAPID Keys - Authenticates your server with push services
Subscription - User's unique identifier for receiving notifications

Step 1: Generate VAPID Keys

VAPID (Voluntary Application Server Identification) keys authenticate your server when sending push notifications.

Install web-push globally

npm install -g web-push

web-push generate-vapid-keys

Generate your keys

You'll see output like this:

=======================================
Public Key:
BKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Private Key:
yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
=======================================

Add to your environment variables

Create or update .env.local:

NEXT_PUBLIC_VAPID_PUBLIC_KEY=BKxxxxxxxxxxx...
VAPID_PRIVATE_KEY=yyyyyyyyyyyy...
VAPID_EMAIL=mailto:your-email@example.com

⚠️ Important:

The public key MUST start with NEXT_PUBLIC_ to be accessible in the browser

Never commit your .env.local file to version control

Keep your private key secret!

Step 2: Setup Database Schema

We need to store user subscriptions so we can send them notifications later.

Update your Prisma schema

Add this model to your prisma/schema.prisma:

model PushSubscription {
  id        String   @id @default(uuid())
  userId    String   // Connect to your User model if you have authentication
  endpoint  String   @unique
  p256dh    String   // Encryption key
  auth      String   // Authentication secret
  userAgent String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([userId])
}

Run the migration

npx prisma migrate dev --name add_push_subscriptions

Step 3: Create the Service Worker

The service worker runs in the background and handles incoming notifications.

Create `public/sw.js`

public/sw.js

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677

// Listen for push events from your server
self.addEventListener('push', function (event) {
console.log('Push notification received:', event);

let notificationData = {
title: 'New Notification',
body: 'You have a new message',
icon: '/icon-192x192.png',
badge: '/badge-72x72.png',
tag: 'notification-1',
data: {
url: '/', // URL to open when clicked
},
};

// Parse notification data sent from server
if (event.data) {
try {
const data = event.data.json();
notificationData = {
title: data.title || notificationData.title,
body: data.body || notificationData.body,
icon: data.icon || notificationData.icon,
badge: data.badge || notificationData.badge,
tag: data.tag || notificationData.tag,
data: data.data || notificationData.data,
};
} catch (e) {
notificationData.body = event.data.text();
}
}

// Show the notification
const promiseChain = self.registration.showNotification(
notificationData.title,
{
body: notificationData.body,
icon: notificationData.icon,
badge: notificationData.badge,
tag: notificationData.tag,
data: notificationData.data,
vibrate: [200, 100, 200], // Vibration pattern
requireInteraction: false,
}
);

event.waitUntil(promiseChain);
});

// Handle notification clicks
self.addEventListener('notificationclick', function (event) {
console.log('Notification clicked:', event);

event.notification.close();

// Open or focus the app
const urlToOpen = event.notification.data?.url || '/';

event.waitUntil(
clients
.matchAll({ type: 'window', includeUncontrolled: true })
.then(function (clientList) {
// Check if app is already open
for (let i = 0; i < clientList.length; i++) {
const client = clientList[i];
if (client.url === urlToOpen && 'focus' in client) {
return client.focus();
}
}
// Open new window if app is not open
if (clients.openWindow) {
return clients.openWindow(urlToOpen);
}
})
);
});

Archive_Valid // UTF-8

Lines: 77

💡 Tip: The service worker must be in the public/ folder and will be accessible at /sw.js

This component handles requesting permission and subscribing users.

Create `components/NotificationBanner.tsx`

components/notification-banner.tsx

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199

'use client';
import { useState, useEffect } from 'react';
import { X, Bell, Check } from 'lucide-react';

export default function NotificationBanner() {
const [show, setShow] = useState(false);
const [loading, setLoading] = useState(false);
const [status, setStatus] = useState('');

useEffect(() => {
// Check if user has already made a decision
const dismissed = localStorage.getItem('notification-banner-dismissed');
const enabled = localStorage.getItem('notifications-enabled');

  // Only show if not dismissed and not enabled
  if (!dismissed && !enabled && 'Notification' in window) {
    // Show after 3 seconds (better UX)
    setTimeout(() => setShow(true), 3000);
  }

}, []);

const enableNotifications = async () => {
try {
setLoading(true);
setStatus('Requesting permission...');

    // Check if service worker is supported
    if (!('serviceWorker' in navigator)) {
      setStatus('Service Worker not supported');
      return;
    }

    // Get VAPID public key
    const vapidKey = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY;
    if (!vapidKey) {
      setStatus('Configuration error');
      console.error('NEXT_PUBLIC_VAPID_PUBLIC_KEY is not set');
      return;
    }

    // Request notification permission
    const permission = await Notification.requestPermission();

    if (permission !== 'granted') {
      setStatus('Permission denied');
      handleDismiss();
      return;
    }

    setStatus('Registering service worker...');

    // Register service worker
    const registration = await navigator.serviceWorker.register('/sw.js', {
      scope: '/',
    });

    // Wait for service worker to be ready
    await navigator.serviceWorker.ready;

    setStatus('Subscribing to push...');

    // Unsubscribe from old subscription if exists
    const existingSubscription =
      await registration.pushManager.getSubscription();
    if (existingSubscription) {
      await existingSubscription.unsubscribe();
    }

    // Subscribe to push notifications
    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(vapidKey),
    });

    setStatus('Saving subscription...');

    // Send subscription to your backend
    const res = await fetch('/api/subscribe', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // Add user ID if you have authentication
        // 'x-user-id': userId,
      },
      body: JSON.stringify(subscription),
    });

    if (res.ok) {
      // Save to localStorage
      localStorage.setItem('notifications-enabled', 'true');
      localStorage.removeItem('notification-banner-dismissed');
      setStatus('✅ Push notifications enabled!');

      // Optional: Send a welcome notification
      setTimeout(async () => {
        await fetch('/api/send-notification', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            title: 'Notifications Enabled! 🎉',
            body: 'You will now receive updates even when the app is closed.',
          }),
        });
      }, 1000);

      // Hide banner after success
      setTimeout(() => setShow(false), 3000);
    } else {
      const error = await res.json();
      setStatus('❌ Failed: {error.error}');
    }
  } catch (err) {
    console.error('Notification setup error:', err);
    setStatus('❌ Failed to enable notifications');
  } finally {
    setLoading(false);
  }

};

const handleDismiss = () => {
localStorage.setItem('notification-banner-dismissed', 'true');
setShow(false);
};

if (!show) return null;

return (

<div className="fixed bottom-4 left-4 right-4 md:left-auto md:right-4 md:max-w-md z-50">
<div className="bg-white border border-gray-200 rounded-lg shadow-lg p-4 relative animate-slide-in">
<button
        onClick={handleDismiss}
        className="absolute top-2 right-2 text-gray-400 hover:text-gray-600 transition"
        aria-label="Dismiss notification banner"
      >
<X size={18} />
</button>

      <div className="flex items-start gap-3">
        <div className="bg-blue-100 rounded-full p-2 flex-shrink-0">
          <Bell size={20} className="text-blue-600" />
        </div>

        <div className="flex-1 pr-4">
          <h3 className="font-semibold text-sm mb-1">
            Enable Push Notifications
          </h3>
          <p className="text-xs text-gray-600 mb-3">
            Get security tips and updates even when the app is closed
          </p>

          {status && (
            <p
              className={'text-xs mb-2 flex items-center gap-1 {
                status.includes('✅')
                  ? 'text-green-600'
                  : status.includes('❌')
                  ? 'text-red-600'
                  : 'text-blue-600'
              }'}
            >
              {status.includes('✅') && <Check size={14} />}
              {status}
            </p>
          )}

          <div className="flex gap-2">
            <button
              onClick={enableNotifications}
              disabled={loading}
              className="px-3 py-1.5 bg-blue-600 text-white rounded text-xs font-medium hover:bg-blue-700 transition disabled:opacity-50 disabled:cursor-not-allowed"
            >
              {loading ? 'Setting up...' : 'Enable'}
            </button>
            <button
              onClick={handleDismiss}
              className="px-3 py-1.5 border border-gray-300 text-gray-700 rounded text-xs font-medium hover:bg-gray-50 transition"
            >
              Not now
            </button>
          </div>
        </div>
      </div>
    </div>
  </div>

);
}

// Utility function to convert VAPID key
function urlBase64ToUint8Array(base64String: string) {
const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
const rawData = atob(base64);
return Uint8Array.from([...rawData].map((char) => char.charCodeAt(0)));
}

Archive_Valid // UTF-8

Lines: 199

Add to your layout

// app/layout.tsx
import NotificationBanner from '@/components/NotificationBanner';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <NotificationBanner />
      </body>
    </html>
  );
}

Step 5: Create API Routes

This saves user subscriptions to your database.

Create app/api/subscribe/route.ts:

app/api/subscribe/route.ts

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566

import { NextRequest, NextResponse } from 'next/server';
import { PrismaClient } from '@prisma/client';
import webpush from 'web-push';

const prisma = new PrismaClient();

// Configure VAPID details
webpush.setVapidDetails(
process.env.VAPID_EMAIL!,
process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
process.env.VAPID_PRIVATE_KEY!
);

export async function POST(req: NextRequest) {
try {
  // Get user ID from your auth system
  // For example: const session = await getServerSession();
  // const userId = session?.user?.id;
  const userId = req.headers.get('x-user-id') || 'anonymous';

  const subscription = await req.json();

  // Validate subscription data
  if (!subscription.endpoint || !subscription.keys) {
    return NextResponse.json(
      { error: 'Invalid subscription data' },
      { status: 400 }
    );
  }

  // Save to database
  const saved = await prisma.pushSubscription.upsert({
    where: { endpoint: subscription.endpoint },
    update: {
      userId,
      p256dh: subscription.keys.p256dh,
      auth: subscription.keys.auth,
      userAgent: req.headers.get('user-agent') ?? 'unknown',
      updatedAt: new Date(),
    },
    create: {
      userId,
      endpoint: subscription.endpoint,
      p256dh: subscription.keys.p256dh,
      auth: subscription.keys.auth,
      userAgent: req.headers.get('user-agent') ?? 'unknown',
    },
  });

  console.log('✅ Push subscription saved:', saved.id);

  return NextResponse.json({
    success: true,
    message: 'Subscription saved successfully',
    subscriptionId: saved.id,
  });

} catch (error) {
console.error('❌ Subscription error:', error);
return NextResponse.json(
{ error: 'Internal server error' },
{ status: 500 }
);
}
}

Archive_Valid // UTF-8

Lines: 66

5.2 Send Notification Route

This sends push notifications to subscribed users.

Create app/api/send-notification/route.ts:

app/api/send-notification/route.ts

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586

import { NextRequest, NextResponse } from 'next/server';
import { PrismaClient } from '@prisma/client';
import webpush from 'web-push';

const prisma = new PrismaClient();

webpush.setVapidDetails(
process.env.VAPID_EMAIL!,
process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
process.env.VAPID_PRIVATE_KEY!
);

export async function POST(req: NextRequest) {
try {
  const { title, body, userId, url, icon, badge } = await req.json();

  // Fetch subscriptions from database
  const subscriptions = await prisma.pushSubscription.findMany({
    where: userId ? { userId } : {}, // Send to specific user or all users
  });

  if (subscriptions.length === 0) {
    return NextResponse.json(
      { error: 'No subscriptions found' },
      { status: 404 }
    );
  }

  // Prepare notification payload
  const payload = JSON.stringify({
    title: title || 'New Notification',
    body: body || 'You have a new update',
    icon: icon || '/icon-192x192.png',
    badge: badge || '/badge-72x72.png',
    data: { url: url || '/' },
  });

  // Send to all subscriptions
  const results = await Promise.allSettled(
    subscriptions.map((sub) =>
      webpush
        .sendNotification(
          {
            endpoint: sub.endpoint,
            keys: {
              p256dh: sub.p256dh,
              auth: sub.auth,
            },
          },
          payload
        )
        .catch(async (error) => {
          // If subscription is no longer valid, remove it
          if (error.statusCode === 410 || error.statusCode === 404) {
            await prisma.pushSubscription.delete({
              where: { id: sub.id },
            });
            console.log('🗑️  Removed invalid subscription:', sub.id);
          }
          throw error;
        })
    )
  );

  const successful = results.filter((r) => r.status === 'fulfilled').length;
  const failed = results.filter((r) => r.status === 'rejected').length;

  console.log('📤 Sent {successful} notifications, {failed} failed ');

  return NextResponse.json({
    success: true,
    sent: successful,
    failed,
    total: subscriptions.length,
  });

} catch (error) {
console.error('❌ Send notification error:', error);
return NextResponse.json(
{ error: 'Failed to send notification' },
{ status: 500 }
);
}
}

Archive_Valid // UTF-8

Lines: 86

Step 6: Testing Your Implementation

Test Locally with HTTPS

Push notifications require HTTPS. Use Next.js experimental HTTPS:

npm install -D @next/experimental-https

Then run:

next dev --experimental-https

Your app will be available at https://localhost:3000

Test the Flow

Open your app at https://localhost:3000
Wait 3 seconds for the banner to appear
Click "Enable" and accept the browser permission
Check your terminal to see the subscription saved
Close the browser completely
Send a test notification (see below)

Send a Test Notification

Use this API route or create a test page:

// Test from your terminal or API client
curl -X POST https://localhost:3000/api/send-notification \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Notification 🔔",
    "body": "This is a test push notification!",
    "url": "/dashboard"
  }'

Or create a test button in your app:

// components/TestNotificationButton.tsx
'use client';

export default function TestNotificationButton() {
  const sendTest = async () => {
    const res = await fetch('/api/send-notification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        title: '🎉 Test Notification',
        body: 'If you see this, push notifications are working!',
        url: '/',
      }),
    });

    const data = await res.json();
    alert(`Sent ${data.sent} notifications!`);
  };

  return (
    <button
      onClick={sendTest}
      className="px-4 py-2 bg-green-600 text-white rounded hover:bg-green-700"
    >
      Send Test Notification
    </button>
  );
}

Step 7: Sending Notifications from Your Backend

Example: Send notification when a new event occurs

// Example: In your API route or server action
import { PrismaClient } from '@prisma/client';
import webpush from 'web-push';

const prisma = new PrismaClient();

webpush.setVapidDetails(
  process.env.VAPID_EMAIL!,
  process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
  process.env.VAPID_PRIVATE_KEY!
);

async function notifyUser(userId: string, message: string) {
  const subscriptions = await prisma.pushSubscription.findMany({
    where: { userId },
  });

  const payload = JSON.stringify({
    title: '🔒 Security Alert',
    body: message,
    icon: '/icon-192x192.png',
    data: { url: '/security' },
  });

  await Promise.all(
    subscriptions.map((sub) =>
      webpush.sendNotification(
        {
          endpoint: sub.endpoint,
          keys: { p256dh: sub.p256dh, auth: sub.auth },
        },
        payload
      )
    )
  );
}

// Usage
await notifyUser('user123', 'Your password will expire in 3 days');

Troubleshooting

Issue: "Permission denied"

Solution: The user clicked "Block" on the notification permission. They need to:

Click the lock icon in the address bar
Find "Notifications" and change to "Allow"
Refresh the page and try again

Issue: "Service Worker not supported"

Solution:

Make sure you're using a modern browser (Chrome 42+, Firefox 44+, Edge 17+)
Safari on iOS requires iOS 16.4+ and the app must be installed to home screen

Issue: Notifications not showing when app is closed

Solution:

Ensure you're using HTTPS (required for service workers)
Check that the service worker is registered: Go to DevTools → Application → Service Workers
Verify subscription is saved in your database
Test with curl to rule out frontend issues

Issue: "Application server key not found"

Solution: Your NEXT_PUBLIC_VAPID_PUBLIC_KEY environment variable is not set correctly. Make sure:

It starts with NEXT_PUBLIC_
You've restarted your dev server after adding it
The key is correct (starts with B and is base64 encoded)

Best Practices

1. Don't Spam Users

Only send relevant, valuable notifications
Allow users to customize notification preferences
Respect "Do Not Disturb" hours

2. Handle Unsubscribes

Add an unsubscribe option:

// app/api/unsubscribe/route.ts
export async function POST(req: NextRequest) {
  const { endpoint } = await req.json();

  await prisma.pushSubscription.delete({
    where: { endpoint },
  });

  return NextResponse.json({ success: true });
}

3. Clean Up Invalid Subscriptions

The send notification route already handles this - it removes subscriptions that return 410 (Gone) errors.

4. Add User Preferences

Let users choose what notifications they want:

model NotificationPreferences {
  id                  String  @id @default(uuid())
  userId              String  @unique
  securityAlerts      Boolean @default(true)
  marketingUpdates    Boolean @default(false)
  productUpdates      Boolean @default(true)
}

5. Test Across Browsers

Different browsers handle notifications differently:

Chrome/Edge: Full support, works when closed
Firefox: Full support, works when closed
Safari (macOS): Requires macOS 13+, works when closed
Safari (iOS): Requires iOS 16.4+, must be installed to home screen

Production Checklist

Before deploying to production:

[x] VAPID keys are set in production environment variables
[x] Service worker is accessible at /sw.js
[x] Database schema is migrated
[x] HTTPS is enabled
[x] Error handling is implemented
[x] Invalid subscriptions are cleaned up automatically
[x] User can unsubscribe
[x] Notification content is relevant and valuable
[x] Icons and badges are properly sized and optimized
[x] Testing completed on multiple browsers
[x] Privacy policy mentions push notifications

Next Steps

Now that you have push notifications working, consider:

Add notification preferences - Let users choose what they want to be notified about
Implement notification history - Show past notifications in your app
Add rich actions - Allow users to take actions directly from notifications
Schedule notifications - Use cron jobs or queue systems to send at specific times
Analytics - Track notification open rates and engagement

Additional Resources

Summary

You've successfully implemented push notifications that:

✅ Work even when the browser is closed
✅ Use a non-intrusive banner for opt-in
✅ Store user preferences in localStorage
✅ Save subscriptions to a database
✅ Can be sent from your backend to specific users or all users
✅ Handle errors and clean up invalid subscriptions

Your users can now stay engaged with your app even when they're not actively using it! 🎉

✍️ Written by Moses Kisakye

Published on October 31, 2025

Complete Guide: Push Notifications in Next.js

Learn how to add push notifications to your Next.js application that work even when the browser is closed. This guide will walk you through every step with clear explanations.

What You'll Build

By the end of this guide, you'll have:

🔔 Push notifications that work when your app is closed
📱 A non-intrusive notification banner
💾 Persistent user preferences with localStorage
🔒 Secure VAPID authentication
📊 A database to store user subscriptions

Prerequisites

Before starting, make sure you have:

Basic knowledge of React and Next.js
A Next.js 13+ project with App Router
Node.js and npm installed
A database setup (we'll use Prisma with PostgreSQL)

How Push Notifications Work

┌─────────────┐      ┌──────────────┐      ┌──────────────┐
│   Browser   │─────▶│  Your Server │─────▶│   Browser   │
│  (User A)   │      │              │      │  (User B)    │
│             │      │  Stores      │      │              │
│  Subscribes │      │  subscription│      │  Receives    │
│  to push    │      │  & sends     │      │  notification│
│             │      │  notifications│     │              │
└─────────────┘      └──────────────┘      └──────────────┘

Key Components:

Service Worker - Runs in the background, receives notifications
Push API - Allows your server to send notifications
VAPID Keys - Authenticates your server with push services
Subscription - User's unique identifier for receiving notifications

Step 1: Generate VAPID Keys

VAPID (Voluntary Application Server Identification) keys authenticate your server when sending push notifications.

Install web-push globally

npm install -g web-push

web-push generate-vapid-keys

Generate your keys

You'll see output like this:

=======================================
Public Key:
BKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Private Key:
yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
=======================================

Add to your environment variables

Create or update .env.local:

NEXT_PUBLIC_VAPID_PUBLIC_KEY=BKxxxxxxxxxxx...
VAPID_PRIVATE_KEY=yyyyyyyyyyyy...
VAPID_EMAIL=mailto:your-email@example.com

⚠️ Important:

The public key MUST start with NEXT_PUBLIC_ to be accessible in the browser

Never commit your .env.local file to version control

Keep your private key secret!

Step 2: Setup Database Schema

We need to store user subscriptions so we can send them notifications later.

Update your Prisma schema

Add this model to your prisma/schema.prisma:

model PushSubscription {
  id        String   @id @default(uuid())
  userId    String   // Connect to your User model if you have authentication
  endpoint  String   @unique
  p256dh    String   // Encryption key
  auth      String   // Authentication secret
  userAgent String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([userId])
}

Run the migration

npx prisma migrate dev --name add_push_subscriptions

Step 3: Create the Service Worker

The service worker runs in the background and handles incoming notifications.

Create `public/sw.js`

public/sw.js

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677

// Listen for push events from your server
self.addEventListener('push', function (event) {
console.log('Push notification received:', event);

let notificationData = {
title: 'New Notification',
body: 'You have a new message',
icon: '/icon-192x192.png',
badge: '/badge-72x72.png',
tag: 'notification-1',
data: {
url: '/', // URL to open when clicked
},
};

// Parse notification data sent from server
if (event.data) {
try {
const data = event.data.json();
notificationData = {
title: data.title || notificationData.title,
body: data.body || notificationData.body,
icon: data.icon || notificationData.icon,
badge: data.badge || notificationData.badge,
tag: data.tag || notificationData.tag,
data: data.data || notificationData.data,
};
} catch (e) {
notificationData.body = event.data.text();
}
}

// Show the notification
const promiseChain = self.registration.showNotification(
notificationData.title,
{
body: notificationData.body,
icon: notificationData.icon,
badge: notificationData.badge,
tag: notificationData.tag,
data: notificationData.data,
vibrate: [200, 100, 200], // Vibration pattern
requireInteraction: false,
}
);

event.waitUntil(promiseChain);
});

// Handle notification clicks
self.addEventListener('notificationclick', function (event) {
console.log('Notification clicked:', event);

event.notification.close();

// Open or focus the app
const urlToOpen = event.notification.data?.url || '/';

event.waitUntil(
clients
.matchAll({ type: 'window', includeUncontrolled: true })
.then(function (clientList) {
// Check if app is already open
for (let i = 0; i < clientList.length; i++) {
const client = clientList[i];
if (client.url === urlToOpen && 'focus' in client) {
return client.focus();
}
}
// Open new window if app is not open
if (clients.openWindow) {
return clients.openWindow(urlToOpen);
}
})
);
});

Archive_Valid // UTF-8

Lines: 77

💡 Tip: The service worker must be in the public/ folder and will be accessible at /sw.js

This component handles requesting permission and subscribing users.

Create `components/NotificationBanner.tsx`

components/notification-banner.tsx

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199

'use client';
import { useState, useEffect } from 'react';
import { X, Bell, Check } from 'lucide-react';

export default function NotificationBanner() {
const [show, setShow] = useState(false);
const [loading, setLoading] = useState(false);
const [status, setStatus] = useState('');

useEffect(() => {
// Check if user has already made a decision
const dismissed = localStorage.getItem('notification-banner-dismissed');
const enabled = localStorage.getItem('notifications-enabled');

  // Only show if not dismissed and not enabled
  if (!dismissed && !enabled && 'Notification' in window) {
    // Show after 3 seconds (better UX)
    setTimeout(() => setShow(true), 3000);
  }

}, []);

const enableNotifications = async () => {
try {
setLoading(true);
setStatus('Requesting permission...');

    // Check if service worker is supported
    if (!('serviceWorker' in navigator)) {
      setStatus('Service Worker not supported');
      return;
    }

    // Get VAPID public key
    const vapidKey = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY;
    if (!vapidKey) {
      setStatus('Configuration error');
      console.error('NEXT_PUBLIC_VAPID_PUBLIC_KEY is not set');
      return;
    }

    // Request notification permission
    const permission = await Notification.requestPermission();

    if (permission !== 'granted') {
      setStatus('Permission denied');
      handleDismiss();
      return;
    }

    setStatus('Registering service worker...');

    // Register service worker
    const registration = await navigator.serviceWorker.register('/sw.js', {
      scope: '/',
    });

    // Wait for service worker to be ready
    await navigator.serviceWorker.ready;

    setStatus('Subscribing to push...');

    // Unsubscribe from old subscription if exists
    const existingSubscription =
      await registration.pushManager.getSubscription();
    if (existingSubscription) {
      await existingSubscription.unsubscribe();
    }

    // Subscribe to push notifications
    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(vapidKey),
    });

    setStatus('Saving subscription...');

    // Send subscription to your backend
    const res = await fetch('/api/subscribe', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // Add user ID if you have authentication
        // 'x-user-id': userId,
      },
      body: JSON.stringify(subscription),
    });

    if (res.ok) {
      // Save to localStorage
      localStorage.setItem('notifications-enabled', 'true');
      localStorage.removeItem('notification-banner-dismissed');
      setStatus('✅ Push notifications enabled!');

      // Optional: Send a welcome notification
      setTimeout(async () => {
        await fetch('/api/send-notification', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            title: 'Notifications Enabled! 🎉',
            body: 'You will now receive updates even when the app is closed.',
          }),
        });
      }, 1000);

      // Hide banner after success
      setTimeout(() => setShow(false), 3000);
    } else {
      const error = await res.json();
      setStatus('❌ Failed: {error.error}');
    }
  } catch (err) {
    console.error('Notification setup error:', err);
    setStatus('❌ Failed to enable notifications');
  } finally {
    setLoading(false);
  }

};

const handleDismiss = () => {
localStorage.setItem('notification-banner-dismissed', 'true');
setShow(false);
};

if (!show) return null;

return (

<div className="fixed bottom-4 left-4 right-4 md:left-auto md:right-4 md:max-w-md z-50">
<div className="bg-white border border-gray-200 rounded-lg shadow-lg p-4 relative animate-slide-in">
<button
        onClick={handleDismiss}
        className="absolute top-2 right-2 text-gray-400 hover:text-gray-600 transition"
        aria-label="Dismiss notification banner"
      >
<X size={18} />
</button>

      <div className="flex items-start gap-3">
        <div className="bg-blue-100 rounded-full p-2 flex-shrink-0">
          <Bell size={20} className="text-blue-600" />
        </div>

        <div className="flex-1 pr-4">
          <h3 className="font-semibold text-sm mb-1">
            Enable Push Notifications
          </h3>
          <p className="text-xs text-gray-600 mb-3">
            Get security tips and updates even when the app is closed
          </p>

          {status && (
            <p
              className={'text-xs mb-2 flex items-center gap-1 {
                status.includes('✅')
                  ? 'text-green-600'
                  : status.includes('❌')
                  ? 'text-red-600'
                  : 'text-blue-600'
              }'}
            >
              {status.includes('✅') && <Check size={14} />}
              {status}
            </p>
          )}

          <div className="flex gap-2">
            <button
              onClick={enableNotifications}
              disabled={loading}
              className="px-3 py-1.5 bg-blue-600 text-white rounded text-xs font-medium hover:bg-blue-700 transition disabled:opacity-50 disabled:cursor-not-allowed"
            >
              {loading ? 'Setting up...' : 'Enable'}
            </button>
            <button
              onClick={handleDismiss}
              className="px-3 py-1.5 border border-gray-300 text-gray-700 rounded text-xs font-medium hover:bg-gray-50 transition"
            >
              Not now
            </button>
          </div>
        </div>
      </div>
    </div>
  </div>

);
}

// Utility function to convert VAPID key
function urlBase64ToUint8Array(base64String: string) {
const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
const rawData = atob(base64);
return Uint8Array.from([...rawData].map((char) => char.charCodeAt(0)));
}

Archive_Valid // UTF-8

Lines: 199

Add to your layout

// app/layout.tsx
import NotificationBanner from '@/components/NotificationBanner';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <NotificationBanner />
      </body>
    </html>
  );
}

Step 5: Create API Routes

This saves user subscriptions to your database.

Create app/api/subscribe/route.ts:

app/api/subscribe/route.ts

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566

import { NextRequest, NextResponse } from 'next/server';
import { PrismaClient } from '@prisma/client';
import webpush from 'web-push';

const prisma = new PrismaClient();

// Configure VAPID details
webpush.setVapidDetails(
process.env.VAPID_EMAIL!,
process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
process.env.VAPID_PRIVATE_KEY!
);

export async function POST(req: NextRequest) {
try {
  // Get user ID from your auth system
  // For example: const session = await getServerSession();
  // const userId = session?.user?.id;
  const userId = req.headers.get('x-user-id') || 'anonymous';

  const subscription = await req.json();

  // Validate subscription data
  if (!subscription.endpoint || !subscription.keys) {
    return NextResponse.json(
      { error: 'Invalid subscription data' },
      { status: 400 }
    );
  }

  // Save to database
  const saved = await prisma.pushSubscription.upsert({
    where: { endpoint: subscription.endpoint },
    update: {
      userId,
      p256dh: subscription.keys.p256dh,
      auth: subscription.keys.auth,
      userAgent: req.headers.get('user-agent') ?? 'unknown',
      updatedAt: new Date(),
    },
    create: {
      userId,
      endpoint: subscription.endpoint,
      p256dh: subscription.keys.p256dh,
      auth: subscription.keys.auth,
      userAgent: req.headers.get('user-agent') ?? 'unknown',
    },
  });

  console.log('✅ Push subscription saved:', saved.id);

  return NextResponse.json({
    success: true,
    message: 'Subscription saved successfully',
    subscriptionId: saved.id,
  });

} catch (error) {
console.error('❌ Subscription error:', error);
return NextResponse.json(
{ error: 'Internal server error' },
{ status: 500 }
);
}
}

Archive_Valid // UTF-8

Lines: 66

5.2 Send Notification Route

This sends push notifications to subscribed users.

Create app/api/send-notification/route.ts:

app/api/send-notification/route.ts

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586

import { NextRequest, NextResponse } from 'next/server';
import { PrismaClient } from '@prisma/client';
import webpush from 'web-push';

const prisma = new PrismaClient();

webpush.setVapidDetails(
process.env.VAPID_EMAIL!,
process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
process.env.VAPID_PRIVATE_KEY!
);

export async function POST(req: NextRequest) {
try {
  const { title, body, userId, url, icon, badge } = await req.json();

  // Fetch subscriptions from database
  const subscriptions = await prisma.pushSubscription.findMany({
    where: userId ? { userId } : {}, // Send to specific user or all users
  });

  if (subscriptions.length === 0) {
    return NextResponse.json(
      { error: 'No subscriptions found' },
      { status: 404 }
    );
  }

  // Prepare notification payload
  const payload = JSON.stringify({
    title: title || 'New Notification',
    body: body || 'You have a new update',
    icon: icon || '/icon-192x192.png',
    badge: badge || '/badge-72x72.png',
    data: { url: url || '/' },
  });

  // Send to all subscriptions
  const results = await Promise.allSettled(
    subscriptions.map((sub) =>
      webpush
        .sendNotification(
          {
            endpoint: sub.endpoint,
            keys: {
              p256dh: sub.p256dh,
              auth: sub.auth,
            },
          },
          payload
        )
        .catch(async (error) => {
          // If subscription is no longer valid, remove it
          if (error.statusCode === 410 || error.statusCode === 404) {
            await prisma.pushSubscription.delete({
              where: { id: sub.id },
            });
            console.log('🗑️  Removed invalid subscription:', sub.id);
          }
          throw error;
        })
    )
  );

  const successful = results.filter((r) => r.status === 'fulfilled').length;
  const failed = results.filter((r) => r.status === 'rejected').length;

  console.log('📤 Sent {successful} notifications, {failed} failed ');

  return NextResponse.json({
    success: true,
    sent: successful,
    failed,
    total: subscriptions.length,
  });

} catch (error) {
console.error('❌ Send notification error:', error);
return NextResponse.json(
{ error: 'Failed to send notification' },
{ status: 500 }
);
}
}

Archive_Valid // UTF-8

Lines: 86

Step 6: Testing Your Implementation

Test Locally with HTTPS

Push notifications require HTTPS. Use Next.js experimental HTTPS:

npm install -D @next/experimental-https

Then run:

next dev --experimental-https

Your app will be available at https://localhost:3000

Test the Flow

Open your app at https://localhost:3000
Wait 3 seconds for the banner to appear
Click "Enable" and accept the browser permission
Check your terminal to see the subscription saved
Close the browser completely
Send a test notification (see below)

Send a Test Notification

Use this API route or create a test page:

// Test from your terminal or API client
curl -X POST https://localhost:3000/api/send-notification \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Notification 🔔",
    "body": "This is a test push notification!",
    "url": "/dashboard"
  }'

Or create a test button in your app:

// components/TestNotificationButton.tsx
'use client';

export default function TestNotificationButton() {
  const sendTest = async () => {
    const res = await fetch('/api/send-notification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        title: '🎉 Test Notification',
        body: 'If you see this, push notifications are working!',
        url: '/',
      }),
    });

    const data = await res.json();
    alert(`Sent ${data.sent} notifications!`);
  };

  return (
    <button
      onClick={sendTest}
      className="px-4 py-2 bg-green-600 text-white rounded hover:bg-green-700"
    >
      Send Test Notification
    </button>
  );
}

Step 7: Sending Notifications from Your Backend

Example: Send notification when a new event occurs

// Example: In your API route or server action
import { PrismaClient } from '@prisma/client';
import webpush from 'web-push';

const prisma = new PrismaClient();

webpush.setVapidDetails(
  process.env.VAPID_EMAIL!,
  process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
  process.env.VAPID_PRIVATE_KEY!
);

async function notifyUser(userId: string, message: string) {
  const subscriptions = await prisma.pushSubscription.findMany({
    where: { userId },
  });

  const payload = JSON.stringify({
    title: '🔒 Security Alert',
    body: message,
    icon: '/icon-192x192.png',
    data: { url: '/security' },
  });

  await Promise.all(
    subscriptions.map((sub) =>
      webpush.sendNotification(
        {
          endpoint: sub.endpoint,
          keys: { p256dh: sub.p256dh, auth: sub.auth },
        },
        payload
      )
    )
  );
}

// Usage
await notifyUser('user123', 'Your password will expire in 3 days');

Troubleshooting

Issue: "Permission denied"

Solution: The user clicked "Block" on the notification permission. They need to:

Click the lock icon in the address bar
Find "Notifications" and change to "Allow"
Refresh the page and try again

Issue: "Service Worker not supported"

Solution:

Make sure you're using a modern browser (Chrome 42+, Firefox 44+, Edge 17+)
Safari on iOS requires iOS 16.4+ and the app must be installed to home screen

Issue: Notifications not showing when app is closed

Solution:

Ensure you're using HTTPS (required for service workers)
Check that the service worker is registered: Go to DevTools → Application → Service Workers
Verify subscription is saved in your database
Test with curl to rule out frontend issues

Issue: "Application server key not found"

Solution: Your NEXT_PUBLIC_VAPID_PUBLIC_KEY environment variable is not set correctly. Make sure:

It starts with NEXT_PUBLIC_
You've restarted your dev server after adding it
The key is correct (starts with B and is base64 encoded)

Best Practices

1. Don't Spam Users

Only send relevant, valuable notifications
Allow users to customize notification preferences
Respect "Do Not Disturb" hours

2. Handle Unsubscribes

Add an unsubscribe option:

// app/api/unsubscribe/route.ts
export async function POST(req: NextRequest) {
  const { endpoint } = await req.json();

  await prisma.pushSubscription.delete({
    where: { endpoint },
  });

  return NextResponse.json({ success: true });
}

3. Clean Up Invalid Subscriptions

The send notification route already handles this - it removes subscriptions that return 410 (Gone) errors.

4. Add User Preferences

Let users choose what notifications they want:

model NotificationPreferences {
  id                  String  @id @default(uuid())
  userId              String  @unique
  securityAlerts      Boolean @default(true)
  marketingUpdates    Boolean @default(false)
  productUpdates      Boolean @default(true)
}

5. Test Across Browsers

Different browsers handle notifications differently:

Chrome/Edge: Full support, works when closed
Firefox: Full support, works when closed
Safari (macOS): Requires macOS 13+, works when closed
Safari (iOS): Requires iOS 16.4+, must be installed to home screen

Production Checklist

Before deploying to production:

[x] VAPID keys are set in production environment variables
[x] Service worker is accessible at /sw.js
[x] Database schema is migrated
[x] HTTPS is enabled
[x] Error handling is implemented
[x] Invalid subscriptions are cleaned up automatically
[x] User can unsubscribe
[x] Notification content is relevant and valuable
[x] Icons and badges are properly sized and optimized
[x] Testing completed on multiple browsers
[x] Privacy policy mentions push notifications

Next Steps

Now that you have push notifications working, consider:

Add notification preferences - Let users choose what they want to be notified about
Implement notification history - Show past notifications in your app
Add rich actions - Allow users to take actions directly from notifications
Schedule notifications - Use cron jobs or queue systems to send at specific times
Analytics - Track notification open rates and engagement

Additional Resources

Summary

You've successfully implemented push notifications that:

Your users can now stay engaged with your app even when they're not actively using it! 🎉

✍️ Written by Moses Kisakye

Published on October 31, 2025

Complete Guide: Push Notifications in Next.js

What You'll Build

Prerequisites

How Push Notifications Work

Step 1: Generate VAPID Keys

Install web-push globally

Generate your keys

Add to your environment variables

Step 2: Setup Database Schema

Update your Prisma schema

Run the migration

Step 3: Create the Service Worker

Create public/sw.js

Step 4: Create the Notification Banner Component

Create components/NotificationBanner.tsx

Add to your layout

Step 5: Create API Routes

5.1 Subscribe Route

5.2 Send Notification Route

Step 6: Testing Your Implementation

Test Locally with HTTPS

Test the Flow

Send a Test Notification

Step 7: Sending Notifications from Your Backend

Example: Send notification when a new event occurs

Troubleshooting

Issue: "Permission denied"

Issue: "Service Worker not supported"

Issue: Notifications not showing when app is closed

Issue: "Application server key not found"

Best Practices

1. Don't Spam Users

2. Handle Unsubscribes

3. Clean Up Invalid Subscriptions

4. Add User Preferences

5. Test Across Browsers

Production Checklist

Next Steps

Additional Resources

Summary

Complete Guide: Push Notifications in Next.js

What You'll Build

Prerequisites

How Push Notifications Work

Step 1: Generate VAPID Keys

Install web-push globally

Generate your keys

Add to your environment variables

Step 2: Setup Database Schema

Update your Prisma schema

Run the migration

Step 3: Create the Service Worker

Create public/sw.js

Step 4: Create the Notification Banner Component

Create components/NotificationBanner.tsx

Add to your layout

Step 5: Create API Routes

5.1 Subscribe Route

5.2 Send Notification Route

Step 6: Testing Your Implementation

Test Locally with HTTPS

Test the Flow

Send a Test Notification

Step 7: Sending Notifications from Your Backend

Example: Send notification when a new event occurs

Troubleshooting

Issue: "Permission denied"

Issue: "Service Worker not supported"

Issue: Notifications not showing when app is closed

Issue: "Application server key not found"

Best Practices

1. Don't Spam Users

2. Handle Unsubscribes

3. Clean Up Invalid Subscriptions

4. Add User Preferences

5. Test Across Browsers

Production Checklist

Next Steps

Additional Resources

Summary

Create `public/sw.js`

Create `components/NotificationBanner.tsx`

Create `public/sw.js`

Create `components/NotificationBanner.tsx`