Next.js Firebase Push Notifications: Full Setup With FCM & Service Worker

Nextjs Push notifications are a powerful way to engage users with your Next.js application even when they're not actively browsing. By leveraging Firebase Cloud Messaging (FCM), you can send targeted messages, alerts, and updates directly to user devices. This guide will walk you through the integration process, providing clear explanations and code examples along the way.

1. How FCM Works with Next.js

Firebase Cloud Messaging (FCM) allows cloud-to-device messaging. In a Next.js app, FCM works through three main components:

• Firebase SDK on the client: Requests permission and retrieves the FCM token.
• Service Worker: Receives and displays background notifications.
• Firebase Console or backend API: Sends messages using the device token.

This flow enables your app to send real-time updates, even when the browser is inactive.

Prerequisites

• A Next js project
• A Firebase project with Cloud Messaging enabled

2. Setting Up Firebase

• If you don't have a Firebase project yet, head to https://console.firebase.google.com/ and create one.
• Within your Firebase project, navigate to the Cloud Messaging section and enable it. Note down your Server Key and VAPID Key (Web Push Certificate).

3. Install Firebase SDK in Next.js

Open your terminal or command prompt and navigate to your Next js project's root directory. Install the necessary Firebase packages using npm or yarn:

npm install firebase

4. Create firebase.ts (or Equivalent)

In your project's root directory (outside of any components), create a file named firebase.ts (or adjust the filename if using a different approach). This file will house your Firebase configuration:

import { initializeApp } from 'firebase/app';

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
  appId: "YOUR_APP_ID",
  measurementId: "YOUR_MEASUREMENT_ID",
};

// Initialize Firebase
const firebaseApp = initializeApp(firebaseConfig);

export default firebaseApp;

Explanation:

• This file imports the initializeApp function from the firebase/app module and initializes Firebase using your project's configuration details.
• Replace the placeholder values with your actual Firebase project credentials.

5. Create Service Worker for Firebase Push Notifications

In your Next js project's public directory, create a file named firebase-messaging-sw.js. This service worker will handle next js push notification behavior:

importScripts('https://www.gstatic.com/firebasejs/10.5.0/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.5.0/firebase-messaging-compat.js');

// Your web app's Firebase configuration
const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
  appId: "YOUR_APP_ID",
  measurementId: "YOUR_MEASUREMENT_ID",
};

firebase.initializeApp(firebaseConfig);

class CustomPushEvent extends Event {
    constructor(data) {
        super('push');

        Object.assign(this, data);
        this.custom = true;
    }
}

/*
 * Overrides push notification data, to avoid having 'notification' key and firebase blocking
 * the message handler from being called
 */
self.addEventListener('push', (e) => {
    // Skip if event is our own custom event
    if (e.custom) return;

    // Kep old event data to override
    const oldData = e.data;

    // Create a new event to dispatch, pull values from notification key and put it in data key,
    // and then remove notification key
    const newEvent = new CustomPushEvent({
        data: {
            ehheh: oldData.json(),
            json() {
                const newData = oldData.json();
                newData.data = {
                    ...newData.data,
                    ...newData.notification,
                };
                delete newData.notification;
                return newData;
            },
        },
        waitUntil: e.waitUntil.bind(e),
    });

    // Stop event propagation
    e.stopImmediatePropagation();

    // Dispatch the new wrapped event
    dispatchEvent(newEvent);
});

const messaging = firebase.messaging();

messaging.onBackgroundMessage((payload) => {
    // console.log('[firebase-messaging-sw.js] Received background message ', payload);

    const { title, body, image, icon, ...restPayload } = payload.data;
    const notificationOptions = {
        body,
        icon: image || '/icons/firebase-logo.png', // path to your "fallback" firebase notification logo
        data: restPayload,
    };
    return self.registration.showNotification(title, notificationOptions);
});

self.addEventListener('notificationclick', (event) => {
    if (event?.notification?.data && event?.notification?.data?.link) {
        self.clients.openWindow(event.notification.data.link);
    }

    // close notification after click
    event.notification.close();
});

Explanation:

• Imports Firebase JavaScript SDK libraries.
• Imports the initialized Firebase app instance.
• Initializes Firebase within the service worker for correct access.
• Defines a CustomPushEvent class to handle structured notification data.
• Listens for the next js push notification event in the service worker.
• Extracts notification data from the payload.
• Creates a new CustomPushEvent with structured data for consistency.
• Stops event propagation and dispatches the new event.
• Accesses the messaging instance and listens for background messages on onBackgroundMessage.
• Displays a notification using self.registration.showNotification.
• Listens for the notificationclick

6. PWA + FCM for Web Push Notifications

To deliver native-like push experiences, combine FCM with Progressive Web App (PWA) capabilities. Ensure:

• Your app includes a valid manifest.json.
• HTTPS is used (required by service workers).
• The service worker is registered correctly.

With this setup, your app can handle push notifications just like a mobile app.

7. Get FCM Token in Next.js using Firebase

To handle Next JS push notifications effectively, you'll need to obtain a Firebase Cloud Messaging (FCM) token that uniquely identifies the user's device. In this step, we'll create a custom hook named useFCMToken.ts that requests notification permission from the user, retrieves the FCM token, and manages it within your Next.js application. This hook simplifies integrating push notifications into your app by encapsulating all the necessary logic in one reusable module.

'use client'
import { useEffect, useState } from 'react';
import { getMessaging, getToken } from 'firebase/messaging';
import firebaseApp from '../firebase/firebase';

const useFcmToken = () => {
  const [token, setToken] = useState('');
  const [notificationPermissionStatus, setNotificationPermissionStatus] = useState('');

  useEffect(() => {
    const retrieveToken = async () => {
      try {
        if (typeof window !== 'undefined' && 'serviceWorker' in navigator) {
          const messaging = getMessaging(firebaseApp);

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

          if (permission === 'granted') {
            const currentToken = await getToken(messaging, {
              vapidKey: 'YOUR_VAPID_KEY', // Replace with your Firebase project's VAPID key
            });
            if (currentToken) {
              setToken(currentToken);
            } else {
              console.log('No registration token available. Request permission to generate one.');
            }
          }
        }
      } catch (error) {
        console.log('Error retrieving token:', error);
      }
    };

    retrieveToken();
  }, []);

  return { fcmToken, notificationPermissionStatus };
};

export default useFcmToken;

Explanation:

• This custom hook handles retrieving the FCM token and notification permission status.
• It uses the useState hook to manage the state of the token and permission status.
• The useEffect hook is used to fetch the token and permission on client-side rendering.
• It checks for browser compatibility and service worker support.
• It requests notification permission and updates the state accordingly.
• If permission is granted, it retrieves the FCM token using getToken.
• The retrieved token or an error message is stored in the state.

8. Handle Foreground Push Notifications in Next.js

Create a file firebaseForeground.js

'use client'
import useFcmToken from "@/utils/hooks/useFCMToken";
import { getMessaging, onMessage } from 'firebase/messaging';
import firebaseApp from '../firebase/firebase';
import { useEffect } from 'react';

export default function FcmTokenComp() {
  const { fcmToken, notificationPermissionStatus } = useFcmToken();

  useEffect(() => {
    if (typeof window !== 'undefined' && 'serviceWorker' in navigator) {
      if (notificationPermissionStatus === 'granted') {
        const messaging = getMessaging(firebaseApp);
        const unsubscribe = onMessage(messaging, (payload) => console.log('Foreground push notification received:', payload));
        return () => {
          unsubscribe(); // Unsubscribe from the onMessage event on cleanup
        };
      }
    }
  }, [notificationPermissionStatus]);

  return null; // This component is primarily for handling foreground notifications
}

Explanation:

• This component handles foreground push notifications received while the user is actively browsing the application.
• It imports the useFcmToken hook to access the token and permission status.
• It utilizes the useEffect hook to listen for foreground messages using onMessage when permission is granted.
• The unsubscribe function cleans up the event listener when the component unmounts.

9. Display Notifications in Next.js App with Firebase

- Render FcmTokenComp in a client-side rendered component:

import FcmTokenComp from '../utils/hooks/firebaseForeground';

function MyApp({ Component, pageProps }) {
  return (
    <div>
      <FcmTokenComp /> {/* Render for foreground notification handling */}
      <Component {...pageProps} />
    </div>
  );
}

10. Next.js Push Notification Use Cases

Push notifications are highly versatile. Here are a few real-world examples:

• Abandoned Cart Reminders: Alert users about items left in their cart.
• Promotional Offers: Send real-time discounts and flash sale alerts.
• Blog Updates: Inform readers when new posts go live to increase traffic.

These examples help demonstrate the practical value of adding push functionality.

Conclusion

Firebase Cloud Messaging (FCM) provides a powerful and convenient way to engage users with your Next JS 15 application even when they're not actively browsing. By following the steps outlined in this guide, you can seamlessly implement Next JS push notifications to send targeted messages, alerts, and updates directly to user devices.

This guide provided a detailed explanation of the setup process, including code examples and implementation details. We explored handling both foreground and background notifications, using custom hooks for efficient FCM token management, and integrating the solution with your client-side components.

When building Next JS push notifications, it's important to consider additional aspects like advanced customization, security best practices, error handling, and testing strategies to ensure a robust and user-friendly experience.

This integration opens doors for various use cases—ranging from real-time updates and abandoned cart reminders to personalized promotions and targeted marketing campaigns. With thoughtful planning and execution, Next JS push notifications can become a key part of your user engagement strategy, helping to deliver a more interactive and responsive application.

Troubleshooting Firebase Messaging in Next.js

Common Issues & Fixes:

• "No registration token available": Ensure the user grants permission and your vapidKey is valid.
• Notifications not showing: Confirm that the firebase-messaging-sw.js file is in the public directory and registered correctly.

Testing Tips:

• Use the Firebase Console to send a test message to your app's token.
• Open DevTools and check the “Application > Service Workers” tab to verify registration.
• Test both foreground (onMessage) and background (onBackgroundMessage) scenarios.

FAQ Section

Q: How do I enable push notifications in Next.js using Firebase?
You’ll need to set up Firebase in your app, request notification permission from the user, and configure a service worker to handle push messages.

Q: What is the correct way to use firebase-messaging-sw.js in Next.js?
Place the file in the /public folder so it can be registered by the browser’s service worker API.

Q: Can I use Firebase Cloud Messaging with Next.js App Router?
Yes, FCM is fully compatible with App Router. Ensure client components and service workers are handled correctly.

Q: How do I handle background and foreground push notifications in Next.js?
Use onBackgroundMessage in the service worker and onMessage in a foreground client-side component.

Q: How to fix Firebase messaging “No registration token available” error?
Check that notification permission has been granted, and that you’re using a valid VAPID key.

Related Blogs:

• Build Serverless Functions in Next.js 14 with Vercel
• Create a Blog with Next.js and Markdown: Step-by-Step Guide
• How to create a Progressive Web App (PWA) with Next.js 14
• Top 10 JavaScript Optimization Techniques for Large Apps
• Learn how to integrate GraphQL with Next.js 14