Forem: novu

open source notification Inbox

Emil Pearce — Tue, 18 Mar 2025 10:26:28 +0000

import React from 'react';
import { Inbox } from '@novu/nextjs';

export function NotificationInbox() {
    return (
        <Inbox 
            applicationIdentifier="YOUR_APPLICATION_IDENTIFIER" 
            subscriberId="YOUR_SUBSCRIBER_ID" 
        />
    );
}

just copy and ship

add a powerful notification inbox to your app with 6 lines of code. It's that simple.

visit our launch on ProductHunt

Novu Winter Season Launch Week

Emil Pearce — Mon, 10 Feb 2025 16:38:54 +0000

Over the past week, we've rolled out some of the most requested features to make notification management even more powerful and efficient.

Whether you're improving your workflow organization, streamlining development, or customizing notifications dynamically, there's something for everyone in this feature-packed update.

Multi-Environment Support

Managing notifications across environments can be complex, but it's essential for delivering seamless user experiences.

Novu's Multi-Environment Support introduces a structured, secure, and efficient way to handle your notification workflows at every stage—from development to production.

Key Capabilities

Isolated Environments: Maintain separate subscriber lists, workflows, and message histories.
Environment-Specific Security: Unique API keys and application identifiers for each environment.
Change Management: Commit and promote updates across development, staging, and production.
Custom Environments: Create additional environments (e.g., QA, Sandbox) for greater flexibility.

Try it out and share your feedback: Multi-Environment Support

Template Store

Building notification workflows from scratch can be repetitive.

The Novu Workflow Template Store provides a library of pre-built, standardized notification workflows for use cases like account security, user engagement, transactional updates, and system alerts.

Why Use Workflow Templates?

Save time: Start with proven, industry-standard workflows.
Ensure consistency: Maintain uniform communication patterns.
Multi-channel support: Works across email, SMS, push, and chat.
Evolving library: More templates are being added regularly.

Request a new template or get started today: Submit a Workflow Template Request

Variable Popover

The Variable Popover makes dynamic content creation in Novu's dashboard effortless—no need to manually write Liquid syntax anymore!

Now, you can pick, configure, and preview variables directly in the UI.

Key Benefits

No more Liquid syntax – Use an intuitive UI to insert variables.
Live Previews – Instantly see how variables render.
Error-Free Transformations – Apply filters (capitalization, date formatting, etc.) with ease.
Quick Modifications – Adjust formats and set default values on the fly.

Experience it in action: Try it now

Auto-Genarated SDKs for TypeScript, Python, Go, and PHP

We’re excited to introduce official Novu SDKs for TypeScript, Python, Go, and PHP! These SDKs make it seamless to integrate enterprise-grade notifications into any application.

What’s New?

Fully typed APIs: Ensuring robust, error-free development.
Idiomatic support: Designed with best practices for each language.
Multi-channel capabilities: Send notifications via email, SMS, push, in-app, and chat.
Live API Playground: Test and interact with Novu’s API instantly.

Get started with the SDKs:

Step Conditions

Step Conditions bring full customization to your workflows, enabling notifications to be triggered based on subscriber data, payload information, and previous step outcomes.

Key Features

Subscriber-Based Conditions: Target users based on locale, isOnline, or lastOnlineAt.
Payload-Driven Conditions: Define actions based on real-time trigger data.
Outcome-Based Conditions: Trigger escalations if previous notifications go unread.
Advanced Logic: Use AND, OR, and nested conditions for complex workflows.
Expanded Operator Library: Comparison, string-based, and range-based filtering.

Explore Step Conditions today: Learn More

What’s Next?

These updates are just the beginning! We’re continuously improving Novu to provide the best experience for notification workflows.

Stay tuned for even more enhancements, and let us know what features you’d love to see next.

🚀 Get started today and take your notification workflows to the next level!

A Developer’s Guide to Choosing the Best Notification Platform

Emil Pearce — Sun, 03 Nov 2024 11:36:31 +0000

Duolingo is well known for its unique usage of rich notifications, which, according to co-founder Luis von Ahn, are “one of the core drivers of Duolingo’s impressive daily user traffic.” This highlights how essential notifications are in keeping customers updated and connected to apps and products. However, designing an efficient notification system is not without its challenges.

“How to build a notification system?” is a common question on platforms like StackOverflow, Quora, and Reddit. The complexity of this process has led developers to seek notification platforms that simplify how notifications are integrated into apps so they don’t have to build from scratch. As such, this guide will provide developers with the necessary knowledge and considerations when choosing a notification platform. Let’s get started.

What are notifications?

Notifications are messages or alerts designed to inform or remind users about specific events or important updates related to an application or service. Different types of notifications are used in digital products, each serving distinct purposes. Some of the main types of notifications include web push notifications, in-app, email, and SMS notifications. Each of these will be explored in detail below:

Push notification

Push notifications are short, clickable messages sent directly to users’ devices from an application, even when they are not actively using it. They are typically popular, with Business of Apps reporting an overall opt-in rate of 60%. Some use cases of push notifications include usage by online retailers and E-commerce apps to alert loyal customers about sales and promotions or on social media platforms to notify users of new messages, likes, or comments.

In-app notifications

In-app notifications appear within the application while users are actively using it. They’re designed to improve the user experience or guide the user to a specific app action without interrupting their flow.

With a 75% open rate, in-app notifications perform better than push notifications. Some common forms of in-app notifications include onboarding tips in the form of modals, tooltips, banners, etc.

Email notifications

Email notifications are usually sent to a user’s email address. They are often more formal and provide more detailed information than other notification types.

Email notifications are especially beneficial for reaching users who may not actively use the app, service, or website but still want to stay informed. Examples of these include newsletters or order confirmations for customers.

SMS notifications

SMS notifications or SMS messages are text messages sent to a user’s mobile phone. They are mobile messaging typically used for urgent or time-sensitive alerts and provide a direct and reliable way to send messages that reach users regardless of their device or internet connection. Due to SMS’s non-reliance on internet connectivity, they are best suited for almost every user base. Use cases for this include sending verification codes, service alerts, etc.

Chat notifications

Chat notifications provide a direct, real-time way of communicating with users through popular messaging platforms such as WhatsApp, Discord, Slack, Microsoft Teams, and Telegram. These notifications allow businesses and communities to reach users in the spaces where they’re already active, making communication seamless and engaging.

Examples:

WhatsApp: Ideal for transactional messages, appointment reminders, and customer service, WhatsApp notifications allow businesses to maintain a personal touch and reach users directly on their mobile devices.
Discord: Popular among gaming communities and tech-focused organizations, Discord notifications are perfect for community updates, event reminders, or server alerts.
Slack: Frequently used by businesses for team communication, Slack notifications keep teams informed on project updates, system alerts, and urgent messages.
Microsoft Teams: A preferred choice for corporate environments, Microsoft Teams notifications are excellent for meeting reminders, project updates, and real-time collaboration, seamlessly integrating with Office 365.
Telegram: Known for its high level of privacy and user control, Telegram notifications can be sent directly to individuals or groups, and it supports notifications from custom bots. These bots can send automated updates, alerts, or other messages, allowing organizations to engage large audiences efficiently and provide real-time information.

Each platform supports unique integrations, allowing notifications to be customized to the audience’s specific needs and preferences.

Next, we’ll explore notification platforms and how they work with the different types of notifications.

What are notification platforms?

Notification platforms are systems or services that enable implementing, creating, sending, and managing notifications. In simple terms, notification platforms are communication channels that facilitate the journey of the notification from creation to execution between the system (developer, business, application) and the receiver (user).

Here’s a typical notification flow facilitated by a service.

Notification platform showing integration with other services and notification delivery to users

Later, we will discuss some popular notification platforms, but first, let’s look at some critical features of notification platforms.

Key features of notification platforms

Notification platforms are equipped with features that improve the experience of the end user and the platform user, which can be the Developer, Business Manager, Analyst, etc.

Some of these key features include:

Customization and personalization
Real-time analytics and reporting
Scalability and reliability
Multi-channel delivery
Integration and compatibility

We’ll look at each and why they matter.

Customization and personalization

Notification platforms often offer robust configuration and sometimes white labeling options that enable businesses to customize, personalize, and notify target users based on brand voice, user preference, demographics, etc.

Customization and segmentation feature on a notification platform

This customization capability makes notification platforms versatile as they can be built once and reimagined per business to suit different use cases.

Real-time analytics and reporting

Robust real-time analytics are a crucial feature of notification platforms as they provide insights into notification performance by tracking key metrics like delivery rates, open rates, click-through rates, and user behavior.

This is particularly useful in A/B testing to experiment with different message formats to identify the most effective approach.

Scalability and reliability

Notification platforms are designed to scale effortlessly, allowing companies to handle large volumes of notifications without compromising performance.

This scalability ensures that businesses maintain effective communication as their user base increases while their notification implementation ideally remains the same.

Multi-channel delivery

As explored earlier, notifications can be of various types, and versatility is one of the core features every notification platform introduces into the build. This versatility is in multi-channel delivery, where multiple communication channels like push notifications, email, and SMS are supported. This ensures businesses can choose the different modes of message delivery as needed.

Integration and compatibility

Notification platforms easily connect with existing systems, applications, and third-party services through APIs and SDKs. This ensures flexibility in using the notification service or platform, including incorporation into existing workflows and systems.

These are all great features and characteristics; however, how do notification platforms benefit the business?

Benefits of using a notification platform

Here are ways notification platforms play a vital role for businesses and developers seeking to enhance user engagement and communication experience:

Improved user engagement

Notifications, among other functions, remind customers to interact and engage with a product. Through multi-channel delivery, users can receive notifications in a convenient format. This, combined with high relevance and customization, helps the business target, engage, and communicate with each user on a more personal level, leading to higher engagement.

Enhanced customer experience

Users turn off notifications or, in extreme cases, delete applications for various reasons, primarily when notifications are sent at inconvenient times or too frequently, leading to notification fatigue and frustration.

However, notification platforms provide valuable analytics on user engagement, such as the optimal time of day to send notifications and the most effective formats for different user segments. Marketing, Product, and Developers can leverage these insights to deliver value and drive engagement by ensuring timely, relevant, and well-paced notifications.

Increased operational efficiency

Notification workflows streamline repetitive communication tasks by automating them end-to-end, significantly reducing the need for manual intervention. Through seamless integration with business systems like customer relationship management (CRM) or marketing automation tools, workflows ensure that critical notifications are triggered automatically at precisely the right time.

For instance, when a new customer is added to the CRM, a notification workflow can automatically initiate a sequence of messages, such as a welcome email followed by onboarding tips, without requiring additional input from the sales or marketing team. This automated workflow not only reduces the workload on customer service teams but also ensures consistency, minimizes human error, and creates a smooth, responsive user experience.

Subscriber (recipient) management

Notification platforms simplify managing large numbers of subscribers by organizing them into specific segments, enabling precise targeting and personalization. Businesses can easily manage subscriber lists, track engagement, and customize notifications to ensure messages are relevant to each user segment, enhancing user satisfaction and engagement.

Multi-tenancy support

Multi-tenancy allows businesses to separate and manage notifications across various clients or brands within a single system, ensuring data privacy and control. This feature enables each tenant to maintain unique subscriber preferences and communication styles, making it easier to provide tailored messaging and achieve the specific goals of each organization while operating under one unified platform.

Better conversion rates

Many notification platforms offer A/B testing features, allowing businesses to experiment with different messaging strategies, formats, and timings. For example, companies can A/B test different subject lines for an email campaign to reveal which version leads to higher open and click-through rates, directly contributing to better retention rates and conversion outcomes.

No-Code tools to manage notifications

With a no-code user interface (no-code editors), teams can adjust notification messaging, verbiage, and cadence without needing engineering support. This empowers marketing, product, and support teams to fine-tune notifications in real-time, ensuring messages are aligned with current campaigns, user feedback, and evolving engagement strategies, all without disrupting development workflows.

Improved timing with scheduling and delay functionality

Notification platforms enable businesses to schedule messages or introduce a delay, ensuring they reach users at the most effective times. For example, a platform can queue up messages to reach a global audience during their respective peak engagement times or delay notifications based on users' time zones and habits. This minimizes disruption and allows users to receive updates when they’re most likely to engage, reducing notification fatigue and increasing relevance.

Better user experience with digest functionality

Digest notifications consolidate multiple updates into a single message, preventing users from feeling overwhelmed by individual alerts. By grouping updates, notification digests enhance user experience and maintain a clean inbox while still keeping users informed. This functionality also benefits companies by keeping users more engaged over time, as they are less likely to opt out of receiving notifications.

Personalized communication through user preferences

Offering users the ability to set their notification preferences—such as which channels to receive updates on, preferred frequency, and specific types of notifications—gives them control over their experience. Platforms that integrate user preferences into their notifications create a more tailored experience, resulting in increased user satisfaction and trust, reduced churn, and a healthier relationship with customers by reducing unwanted alerts.

So far, we know why notification platforms are important and what to expect from the right service. Based on our needs, let’s consider some of the available notification services and providers that could be integrated into the notification platform.

Popular notification services and providers

Established services can significantly accelerate development, ensuring scalability and letting teams focus on core product enhancements. Here’s an overview of popular notification providers, each playing a unique role in a robust notification strategy.

Push notification providers

Firebase Cloud Messaging (FCM)

FCM is part of Google’s Firebase suite and provides a streamlined, cost-free option for sending push notifications to web and mobile apps. Best suited for developers already leveraging other Firebase tools, FCM ensures easy integration with Google’s ecosystem, enabling efficient, low-cost notifications. Top brands like Sony rely on FCM for its ease and reliability.

OneSignal

OneSignal is an all-in-one messaging solution offering push, in-app messaging, email, and SMS notifications. Ideal for multi-channel strategies, it provides features like A/B testing, segmentation, and personalized messaging. Its user-friendly interface makes managing and optimizing campaigns simple, allowing product teams to drive user engagement across multiple channels.

Amazon Simple Notification Service (SNS)

Amazon SNS, part of the AWS ecosystem, is designed for high-volume, secure messaging across SMS, email, and mobile push. Product teams in regulated industries find SNS particularly useful for its compliance-ready infrastructure, reliability, and scalability within AWS—making it ideal for apps needing robust security and compliance.

Airship

Airship focuses on mobile-first engagement, with services spanning push notifications, in-app messaging, and deeper analytics. It’s particularly suited for product teams aiming to improve mobile user retention and engagement through highly targeted messaging, making it a strong choice for mobile-centric applications.

Microsoft Azure Notification Hubs

Azure Notification Hubs offers a global push notification solution with support across Android, iOS, Windows, and Kindle. Compatible with Baidu for China, it’s an excellent choice for products requiring broad international reach within the Azure ecosystem, providing reliable scalability and performance.

SMS notification providers

SMS notifications are key for urgent, direct communication with users.

Twilio

A leading choice for SMS notifications, Twilio provides extensive global coverage, developer-friendly APIs, and flexible pricing for businesses of all sizes. Its reliability and ease of use make it a favorite for teams needing scalable SMS integration in their applications.

Nexmo (Vonage)

Nexmo supports SMS, voice, and verification services, focusing on simplicity and high deliverability. Its developer-friendly platform is ideal for teams looking to implement reliable communication channels quickly and effectively.

Plivo

Plivo offers cost-efficient SMS and voice solutions with a global reach. Designed for high-volume messaging, it provides transparent pricing and is a practical choice for applications needing affordable yet powerful SMS capabilities.

Sinch

Sinch specializes in SMS and voice with rich media support, which is ideal for businesses seeking to send multimedia messages or engage users more interactively, especially for marketing or customer support use cases.

MessageBird

MessageBird supports SMS, voice, and chat APIs, making it suitable for multi-channel applications. With a strong API focus, MessageBird is ideal for global teams wanting seamless integration and wide-reaching SMS capabilities.

Email notification providers

Email notifications are crucial for transactional, marketing, and engagement communication.

SendGrid

SendGrid is known for its high deliverability and robust APIs, supporting both transactional and marketing emails. With advanced analytics, it’s favored by teams seeking to optimize user engagement and gain insights into email performance.

Amazon SES (Simple Email Service)

Amazon SES is a cost-effective email solution within the AWS ecosystem. With easy scalability and high deliverability, it’s ideal for applications needing large-scale, budget-friendly email capabilities in the cloud.

Mailgun

Mailgun offers a developer-focused API with advanced analytics, making it a strong choice for teams needing customized email flows and insights. Its flexibility supports complex email strategies tailored to user behavior.

Postmark

Postmark specializes in transactional email, prioritizing speed and reliability. It’s particularly suited for critical communications like password resets and verification emails, ensuring fast delivery and optimized uptime.

SparkPost

SparkPost combines reliable deliverability with data-driven insights, providing a solid choice for teams focused on maximizing email engagement through real-time analytics.

Chat notification providers

Chat notifications allow for real-time user engagement on familiar platforms.

Slack API

Slack API is perfect for internal team alerts and notifications, allowing developers to integrate system messages directly into Slack channels or DMs, enhancing team awareness and response times.

Twilio WhatsApp API

WhatsApp via Twilio enables secure, engaging communication for updates like order status and appointment reminders. This is ideal for teams needing a reliable, globally popular channel for direct customer engagement.

Messenger Platform

Facebook Messenger offers a popular real-time communication channel within the Facebook ecosystem. It’s especially useful for customer support and instant notifications.

Telegram Bot API

Telegram provides secure, customizable notifications to individual users or groups, making it ideal for platforms with a privacy-focused user base or those that value security.

Discord API

Discord API supports direct and channel-based notifications, making it perfect for community-driven platforms and teams needing effective real-time updates for collaborative environments.

In-App Notification Providers

In-app notifications allow teams to engage users directly within the application, enhancing user experience and driving interaction without disrupting the user journey.

Novu

Novu is an open-source, in-app notification solution offering ready-to-use components that simplify implementation and boost user engagement. With customizable notification feeds, preference centers, and real-time delivery, Novu allows teams to quickly deploy tailored in-app notifications that enhance user experience without the overhead of custom development. Designed for flexibility, Novu’s SDKs and workflows ensure seamless integration, giving teams complete control over notification appearance and behavior.

Airship

In addition to push notifications, Airship offers in-app messaging designed to enhance user engagement within mobile apps. Airship’s in-app notifications are customizable, providing detailed analytics and targeting capabilities. This makes it a strong choice for product teams focused on personalized messaging that aligns with users’ in-app behavior.

Firebase In-App Messaging

Firebase In-App Messaging allows product teams to send targeted messages to active app users. It’s particularly effective for guiding users through the app, promoting features, or highlighting special offers. Best suited for teams already using Firebase, it offers easy integration with other Google tools, providing a seamless way to enhance the in-app experience.

Supabase

Supabase provides real-time database capabilities, making it well-suited for event-driven in-app notifications. Through database triggers and real-time APIs, Supabase allows developers to send notifications based on specific user actions or data changes, creating an interactive, responsive user experience.

OneSignal

While primarily known for push and SMS, OneSignal also supports in-app messaging, making it a flexible option for multi-channel engagement. Its in-app messaging features are customizable and can be integrated alongside other notification types, ideal for teams seeking a single platform for all messaging needs.

In summary, while these other notification platforms offer unique functionalities, Novu encompasses their capabilities and provides a comprehensive solution for developers looking to implement robust notification systems.

How do you choose these notification platforms? Let’s find out.

Choosing the right notification platform

Selecting the right notification platform is a critical decision that can significantly impact an application's success. A notification platform is a centralized, end-to-end system (or infrastructure) that empowers product and development teams to manage, deliver, and optimize multi-channel notifications across in-app, email, SMS, push, and chat channels.

To make an informed choice, I recommend you consider several essential factors to verify that they align with your specific needs and goals.

Here’s a closer look at some of these factors:

Ease of integration

When choosing a notification platform, one of the first considerations should be how easily it can be integrated into an existing tech stack. A platform like Novu has a straightforward integration process, well-documented APIs, and support resources that can save the development team time and reduce the risk of implementation errors.

Here are some other common things to look out for:

Clear and comprehensive documentation
SDKs and libraries for the preferred programming languages
Examples and tutorials for common use cases
Availability of technical support or community assistance

For instance, Novu provides all of these, allowing for easy integrations.

Cost-effectiveness

Cost is a key consideration, especially for startups and small businesses with limited budgets. It’s important to weigh the price against the platform’s value for the project. Each platform’s pricing differs, so be sure to check that and consider any rate limits that may apply.

Novu offers three pricing tiers, ranging from free to enterprise, that cater to a variety of needs, from open-source projects and startups to large-scale enterprise solutions.

Feature set

The feature set of a notification platform determines its ability to meet specific goals. It is best to draw a plan of the project goal and use this to determine the feature set to look for.

Novu, for example, supports a diverse range of features, including multi-channel support and real-time analytics.

Scalability

Scalability is vital so the platform can grow alongside the business without compromising efficiency or risking downtimes. In this regard, when determining the scalability of a notification platform, check for the following:

The platform’s ability to handle large volumes of notifications during peak times
Load balancing and failover mechanisms to provide consistent performance
Support for global delivery, especially if the user base is international

A notification platform like Novu supports scalability using microservices and Kubernetes, which ensures the platform can support growing requests through horizontal scaling (adding more servers or nodes).

Security and compliance

Security and compliance are paramount, especially when handling sensitive user data. Checking reviews and case studies can provide insights into the platform’s reliability and security track record. Beyond that, also look out for the following:

End-to-end encryption for data in transit and at rest
Access control and audit logs for monitoring usage and permissions
Regular security updates and vulnerability management

Novu puts security at the core of its operations, strictly adhering to industry standards for data protection and complying with relevant regulations.

To make the best decision, thorough research is necessary, including subscribing to the notification platform of choice and testing it against the business’s functional and non-functional requirements.

After choosing the right platform, you get to design the system. Here are some best practices to follow when considering notification design.

Best practices for notification design

Designing efficient and user-friendly notifications requires balancing user, business, and legal rules.

Respecting user preferences

Respecting user preferences enhances user satisfaction and reduces the risk of notification fatigue, where users become overwhelmed and may choose to turn off notifications altogether. To avoid this, make sure users can customize their notification preferences to select the type of notifications they receive, the delivery channel, and the delivery frequency.

In cases where users cannot choose the delivery frequency, analytics from the notification platform can reveal the number of times users are most likely to read notifications. This information can help you better time your notifications.

Maintaining compliance with regulations

Compliance with regulations avoids legal repercussions and builds trust with users, who are increasingly concerned about how their data is used. To enforce this practice, always obtain explicit consent from users before sending notifications.

Ensuring data security

Data security protects users and organizations from potential breaches, data theft, and the associated legal and reputational damage. To counter this, implement end-to-end encryption for notifications, ensuring that data is protected in transit and at rest. This is especially important for sensitive information such as account alerts or transactional messages.

Regular security assessments and audits should also be conducted to identify potential vulnerabilities in the notification system.

Providing opt-out options

Providing opt-out options is a legal requirement in many jurisdictions and critical to maintaining a positive user experience. For instance, users might choose to receive email notifications but opt out of push notifications or even choose to opt out of all notifications completely. As a result, ensure users can easily opt out of all or a few notifications.

Wrapping up

Using established notification platforms is often a simpler and more efficient alternative to building an in-house solution. However, choosing the right notification platform is a tough decision and can impact the business for better or for worse.

This guide covers some critical points in choosing an effective notification platform. Novu stands out for its modern, open-source approach, which provides developers with flexibility and control.

Sign up for Novu for a cost-effective, customizable notification solution with a strong focus on end-user and developer experience.

How to Build a Notion-Like Notification Inbox with Chakra UI and Novu

Emil Pearce — Wed, 02 Oct 2024 20:01:09 +0000

TL;DR

In this short post, you will learn about how I recreated a fully functional, real-time, notification inbox component that replicates Notion’s built-in notifications capability by using only Chakra UI for the design and Novu for the notifications.

This is how it looks:

The link to the source code and the deployed version of this app are at the end of the post.

As a daily Notion user, I really appreciate their notifications experience, and it’s a huge part of why I use their app so heavily. I was curious—how could I recreate an inbox similar to Notion's sleek notification system? Turns out, it's quite straightforward, thanks to Novu's in-app notification component.

Novu recently launched their full-stack notification component—a stateful, embeddable React component or widget that's customizable and ready to go.

Here’s how you can add it to your React app in just a few simple steps:

Install the Novu package
```
$ npm install @novu/react
```
Import the component
```
import { Inbox } from "@novu/react";
```

Initialize the component in your app

function Novu() {
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriberId="YOUR_SUBSCRIBER_ID"
    />
  );
}

That’s it! You’ve now got a fully functional in-app inbox component.

Out of the box, it looks pretty awesome:

Not to brag, but Novu’s Inbox also happens to be the most flexible and customizable out there. Check out how to style it, and even experiment for yourself.

If you're interested in the tech behind it, Novu's Co-Founder Dima Grossman wrote a great post on how and why they built it.

Styling your Inbox like Notion

Want your inbox to look like Notion’s notification panel? Not a problem! You can easily wrap and customize Novu’s notifications to fit Notion’s clean, minimal aesthetic.

How I did it

Instead of just importing the Inbox component from @novu/react, I brought in the Notification and Notifications components for full control over rendering each item.

import { Inbox, Notification, Notifications } from "@novu/react";

What’s inside a notification?

Before we start customizing, here's the structure of a notification object:

interface Notification = {
  id: string;
  subject?: string;
  body: string;
  to: Subscriber;
  isRead: boolean;
  isArchived: boolean;
  createdAt: string;
  readAt?: string | null;
  archivedAt?: string | null;
  avatar?: string;
  primaryAction?: Action;
  secondaryAction?: Action;
  channelType: ChannelType;
  tags?: string[];
  data?: Record<string, unknown>;
  redirect?: Redirect;
};

Armed with this, I used Chakra UI (because wrangling Tailwind classes is exhausting) to design each notification item.

Custom inbox item component

Here’s how I created a Notion-inspired notification item:

const InboxItem = ({ notification }: { notification: Notification }) => {
    const [isHovered, setIsHovered] = useState(false);
    const notificationType = notification.tags?.[0];

    return (
        <Box
            p={2}
            bg="white"
            position="relative"
            onMouseEnter={() => setIsHovered(true)}
            onMouseLeave={() => setIsHovered(false)}
        >
            <Flex align="flex-start" position="relative">
                <VStack spacing={0} position="absolute" top="0" right="0">
                    {isHovered && (
                        <Box bg="white" display="flex" gap={1}>
                            {notification.isRead ? (
                                <IconButton
                                    aria-label="Mark as unread"
                                    icon={<PiNotificationFill />}
                                    onClick={() => notification.unread()}
                                    size="sm"
                                    variant="ghost"
                                />
                            ) : (
                                <IconButton
                                    aria-label="Mark as read"
                                    icon={<FaRegCheckSquare />}
                                    onClick={() => notification.read()}
                                    size="sm"
                                    variant="ghost"
                                />
                            )}
                            {notification.isArchived ? (
                                <IconButton
                                    aria-label="Unarchive"
                                    icon={<PiNotificationFill />}
                                    onClick={() => notification.unarchive()}
                                    size="sm"
                                    variant="ghost"
                                />
                            ) : (
                                <IconButton
                                    aria-label="Archive"
                                    icon={<FiArchive />}
                                    onClick={() => notification.archive()}
                                    size="sm"
                                    variant="ghost"
                                />
                            )}
                        </Box>
                    )}
                </VStack>

                <Box
                    position="relative"
                    display="flex"
                    alignItems="center"
                    mr="8px"
                    height="26px"
                >
                    {!notification.isRead && (
                        <Box>
                            <Box width="8px" height="8px" bg="blue.500" borderRadius="full" />
                        </Box>
                    )}
                    {notification.avatar !== undefined && (
                        <Avatar
                            width="24px"
                            height="24px"
                            marginLeft="8px"
                            name={notification.to.firstName}
                            src={notification.avatar || undefined}
                        />
                    )}
                </Box>

                <VStack align="start" spacing="8px" flex="1" mt="3px">
                    <Flex justify="space-between" width="100%">
                        <Text fontSize="14px" color="gray.800" fontWeight="600">
                            {notification.subject}
                        </Text>
                        <Text fontSize="xs" color="gray.400">
                            {formatTime(notification.createdAt)}
                        </Text>
                    </Flex>

                    {notificationType !== "Mention" &&
                        notificationType !== "Comment" &&
                        notificationType !== "Invite" && (
                            <Text fontSize="14px" color="gray.800">
                                {notification.body}
                            </Text>
                        )}

                    {(notificationType === "Mention" ||
                        notificationType === "Comment") && (
                            <Button
                                variant="ghost"
                                size="sm"
                                leftIcon={<GrDocumentText />}
                                _hover={{ bg: "rgba(0, 0, 0, 0.03)" }}
                                pl="2px"
                                pr="5px"
                                height="25px"
                            >
                                <Text
                                    fontSize="14px"
                                    color="gray.800"
                                    fontWeight="500"
                                    backgroundImage="linear-gradient(to right, rgba(55, 53, 47, 0.16) 0%, rgba(55, 53, 47, 0.16) 100%)"
                                    backgroundRepeat="repeat-x"
                                    backgroundSize="100% 1px"
                                    backgroundPosition="0 100%"
                                    mr="-2px"
                                >
                                    {notification.body}
                                </Text>
                            </Button>
                        )}

                    {notificationType === "Invite" && (
                        <Button
                            variant="outline"
                            size="md"
                            _hover={{ bg: "rgba(0, 0, 0, 0.03)" }}
                            padding="12px"
                            height="50px"
                            fontSize="14px"
                            width="100%"
                            borderRadius="8px"
                            textAlign="left"
                            border="1px solid rgba(227, 226, 224, 0.5)"
                            justifyContent="space-between"
                        >
                            {notification.body}
                        </Button>
                    )}

                    {notificationType === "Comment" && (
                        <Box>
                            <Text fontSize="12px" color="rgb(120, 119, 116)" fontWeight="400">
                                John Doe
                            </Text>
                            <Text fontSize="14px" color="rgb(55, 53, 47)" fontWeight="400">
                                This is a notification Comment made by John Doe and posted on
                                the page Top Secret Project
                            </Text>
                        </Box>
                    )}

                    <HStack spacing={3}>
                        {notification.primaryAction && (
                            <Button
                                variant="outline"
                                size="xs"
                                colorScheme="gray"
                                borderRadius="md"
                                borderColor="gray.300"
                                _hover={{ bg: "gray.100" }}
                                paddingRight="8px"
                                paddingLeft="8px"
                                lineHeight="26px"
                                height="26px"
                            >
                                {notification.primaryAction.label}
                            </Button>
                        )}
                        {notification.secondaryAction && (
                            <Button
                                variant="ghost"
                                size="xs"
                                colorScheme="gray"
                                borderRadius="md"
                                borderColor="gray.300"
                                _hover={{ bg: "gray.100" }}
                                paddingRight="8px"
                                paddingLeft="8px"
                                lineHeight="26px"
                                height="26px"
                            >
                                {notification.secondaryAction.label}
                            </Button>
                        )}
                    </HStack>
                </VStack>
            </Flex>
        </Box>
    );
};

Notification object keys

As you can see in the code, I utilized the following notification keys:

notification.tags
notification.isRead
notification.isArchived
notification.to.firstName
notification.avatar
notification.subject
notification.createdAt
notification.body
notification.primaryAction
notification.primaryAction.label
notification.secondaryAction
notification.secondaryAction.label

The notification.data object can contain any practical piece of information that your application logic would like to associate with a user or subscriber. This flexible structure allows you to tailor notifications to specific use cases and provide richer, more contextual information to your users.

Examples of using notification.data:

E-commerce order updates:

notification.data = {
  orderId: "ORD-12345",
  status: "shipped",
  trackingNumber: "1Z999AA1234567890",
  estimatedDelivery: "2023-09-25"
};

Social media interactions:

notification.data = {
  postId: "post-789",
  interactionType: "like",
  interactingUser: "johndoe",
  interactionTime: "2023-09-22T14:30:00Z"
};

Financial transactions:

notification.data = {
  transactionId: "TRX-98765",
  amount: 150.75,
  currency: "USD",
  merchantName: "Coffee Shop",
  category: "Food & Drink"
};

By utilizing the notification.data object, you can create more informative and actionable notifications that seamlessly integrate with your application's specific requirements.

This flexibility allows you to provide users with precisely the information they need, enhancing their experience and the overall effectiveness of your notification system.

Using hooks for notification management

If you've examined the code closely, you may have noticed the use of four key hooks to manage notification states:

notification.unread()
notification.read()
notification.unarchive()
notification.archive()

The novu/react package exposes these hooks, offering enhanced flexibility for managing notification states. It's important to note that these hooks not only update the local state but also synchronize changes with the backend.

These hooks provide a seamless way to:

Mark notifications as read or unread
Archive or unarchive notifications

By utilizing these hooks, you can create more interactive and responsive notification systems in your applications.

I've implemented Notion-inspired sidebar navigation to enhance the similarity to the Notion theme. This design choice aims to capture the essence and aesthetics of Notion's interface, creating a familiar and intuitive environment for users.

For the icons, I've leveraged the versatile react-icons library, which offers a wide range of icon sets to choose from.

$ npm install react-icons

import { FiArchive, FiSearch, FiHome, FiInbox, FiSettings, FiChevronDown } from "react-icons/fi";
import { FaRegCheckSquare, FaUserFriends } from "react-icons/fa";
import { PiNotificationFill } from "react-icons/pi";
import { BsFillFileTextFill, BsTrash } from "react-icons/bs";
import { AiOutlineCalendar } from "react-icons/ai";
import { GrDocumentText } from "react-icons/gr";

const AppContainer = () => {
    const borderColor = useColorModeValue("gray.200", "gray.700");
    const [isInboxOpen, setIsInboxOpen] = useState(true);

    const toggleInbox = () => {
        setIsInboxOpen(!isInboxOpen);
    };

    return (
        <Flex
            width="100vw"
            height="100vh"
            bg="gray.100"
            overflow="hidden"
            justifyContent="center"
            alignItems="center"
            style={{
                fontFamily:
                    'ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI Variable Display", "Segoe UI", Helvetica, "Apple Color Emoji", Arial, sans-serif, "Segoe UI Emoji", "Segoe UI Symbol"',
            }}
        >
            <Box
                width="80%"
                height="80%"
                bg="white"
                borderRadius="lg"
                boxShadow="xl"
                overflow="hidden"
            >
                <Flex height="100%">
                    {/* Sidebar */}
                    <Box
                        width="240px"
                        bg="rgb(247, 247, 245)"
                        padding="8px"
                        display="flex"
                        flexDirection="column"
                        borderColor={borderColor}
                        borderRightWidth="1px"
                    >
                        <Flex alignItems="center" mb="4px" padding="0.6rem">
                            <Text
                                fontSize="1.25rem"
                                fontWeight="bold"
                                color="rgb(55, 53, 47)"
                            >
                                <Icon
                                    as={NotionIcon}
                                    sx={{
                                        width: "20px",
                                        height: "20px",
                                        marginRight: "8px",
                                        display: "inline-block",
                                    }}
                                />{" "}
                                Workspace
                            </Text>
                            <IconButton
                                aria-label="User Settings"
                                icon={<FiChevronDown />}
                                variant="ghost"
                                size="sm"
                            />
                        </Flex>

                        <VStack align="stretch" spacing={1} mb="15px">
                            <SidebarItem icon={FiSearch} label="Search" />
                            <SidebarItem icon={FiHome} label="Home" />
                            <SidebarItem icon={FiInbox} label="Inbox" isActive={isInboxOpen} onClick={toggleInbox} />
                            <SidebarItem icon={FiSettings} label="Settings & members" />
                        </VStack>

                        <Text fontSize="xs" fontWeight="bold" color="gray.500" mb={2}>
                            Favorites
                        </Text>
                        <VStack align="stretch" spacing={1} mb="15px">
                            <SidebarItem icon={FiHome} label="Teamspaces" />
                            <SidebarItem icon={BsFillFileTextFill} label="Shared" />
                        </VStack>

                        <Text fontSize="xs" fontWeight="bold" color="gray.500" mb={2}>
                            Private
                        </Text>
                        <VStack align="stretch" spacing={1} mb="15px">
                            <SidebarItem icon={AiOutlineCalendar} label="Calendar" />
                            <SidebarItem icon={FaUserFriends} label="Templates" />
                            <SidebarItem icon={BsTrash} label="Trash" />
                        </VStack>
                    </Box>

// ... (rest of the code)

Another important aspect was time formatting to match how Notion does it:

function formatTime(timestamp: number | string | Date): string {
    const date = new Date(timestamp);
    const now = new Date();
    const diffInSeconds = Math.floor((now.getTime() - date.getTime()) / 1000);
    const secondsInMinute = 60;
    const secondsInHour = secondsInMinute * 60;
    const secondsInDay = secondsInHour * 24;
    const secondsInWeek = secondsInDay * 7;
    const secondsInYear = secondsInDay * 365;

    if (diffInSeconds < secondsInMinute) {
        return `${diffInSeconds} seconds`;
    } else if (diffInSeconds < secondsInHour) {
        const minutes = Math.floor(diffInSeconds / secondsInMinute);
        return `${minutes} minute${minutes !== 1 ? 's' : ''}`;
    } else if (diffInSeconds < secondsInDay) {
        const hours = Math.floor(diffInSeconds / secondsInHour);
        return `${hours} hour${hours !== 1 ? 's' : ''}`;
    } else if (diffInSeconds < secondsInWeek) {
        const days = Math.floor(diffInSeconds / secondsInDay);
        return `${days} day${days !== 1 ? 's' : ''}`;
    } else if (diffInSeconds < secondsInYear) {
        const options: Intl.DateTimeFormatOptions = { month: "short", day: "numeric" };
        return date.toLocaleDateString(undefined, options);
    } else {
        return date.getFullYear().toString();
    }
}

Now that we have covered all the pieces, here is the complete code:

'use client'
import React, { useState } from 'react';
import {
    Box,
    Flex,
    Text,
    IconButton,
    VStack,
    Avatar,
    HStack,
    Link,
    Icon,
    useColorModeValue,
    Button,
    Heading,
} from "@chakra-ui/react";
import { FiArchive, FiSearch, FiHome, FiInbox, FiSettings, FiChevronDown } from "react-icons/fi";
import { FaRegCheckSquare, FaUserFriends } from "react-icons/fa";
import { PiNotificationFill } from "react-icons/pi";
import { BsFillFileTextFill, BsTrash } from "react-icons/bs";
import { AiOutlineCalendar } from "react-icons/ai";
import { GrDocumentText } from "react-icons/gr";
import { Inbox, Notification, Notifications } from "@novu/react";
import { NotionIcon } from "../icons/Notion";

const subscriberId = process.env.NEXT_PUBLIC_SUBSCRIBERID;
const applicationIdentifier = process.env.NEXT_PUBLIC_NOVU_CLIENT_APP_ID;

const AppContainer = () => {
    const borderColor = useColorModeValue("gray.200", "gray.700");
    const [isInboxOpen, setIsInboxOpen] = useState(true);

    const toggleInbox = () => {
        setIsInboxOpen(!isInboxOpen);
    };

    return (
        <Flex
            width="100vw"
            height="100vh"
            bg="gray.100"
            overflow="hidden"
            justifyContent="center"
            alignItems="center"
            style={{
                fontFamily:
                    'ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI Variable Display", "Segoe UI", Helvetica, "Apple Color Emoji", Arial, sans-serif, "Segoe UI Emoji", "Segoe UI Symbol"',
            }}
        >
            <Box
                width="80%"
                height="80%"
                bg="white"
                borderRadius="lg"
                boxShadow="xl"
                overflow="hidden"
            >
                <Flex height="100%">
                    {/* Sidebar */}
                    <Box
                        width="240px"
                        bg="rgb(247, 247, 245)"
                        padding="8px"
                        display="flex"
                        flexDirection="column"
                        borderColor={borderColor}
                        borderRightWidth="1px"
                    >
                        <Flex alignItems="center" mb="4px" padding="0.6rem">
                            <Text
                                fontSize="1.25rem"
                                fontWeight="bold"
                                color="rgb(55, 53, 47)"
                            >
                                <Icon
                                    as={NotionIcon}
                                    sx={{
                                        width: "20px",
                                        height: "20px",
                                        marginRight: "8px",
                                        display: "inline-block",
                                    }}
                                />{" "}
                                Workspace
                            </Text>
                            <IconButton
                                aria-label="User Settings"
                                icon={<FiChevronDown />}
                                variant="ghost"
                                size="sm"
                            />
                        </Flex>

                        <VStack align="stretch" spacing={1} mb="15px">
                            <SidebarItem icon={FiSearch} label="Search" />
                            <SidebarItem icon={FiHome} label="Home" />
                            <SidebarItem icon={FiInbox} label="Inbox" isActive={isInboxOpen} onClick={toggleInbox} />
                            <SidebarItem icon={FiSettings} label="Settings & members" />
                        </VStack>

                        <Text fontSize="xs" fontWeight="bold" color="gray.500" mb={2}>
                            Favorites
                        </Text>
                        <VStack align="stretch" spacing={1} mb="15px">
                            <SidebarItem icon={FiHome} label="Teamspaces" />
                            <SidebarItem icon={BsFillFileTextFill} label="Shared" />
                        </VStack>

                        <Text fontSize="xs" fontWeight="bold" color="gray.500" mb={2}>
                            Private
                        </Text>
                        <VStack align="stretch" spacing={1} mb="15px">
                            <SidebarItem icon={AiOutlineCalendar} label="Calendar" />
                            <SidebarItem icon={FaUserFriends} label="Templates" />
                            <SidebarItem icon={BsTrash} label="Trash" />
                        </VStack>
                    </Box>

                    {/* Main Content Area */}
                    <Box
                        flex="1"
                        bg="white"
                        height="100%"
                        display="flex"
                        flexDirection="column"
                        justifyContent="center"
                        p={0}
                        position="relative"
                    >
                        {/* Injected Content Behind the Inbox */}
                        <Box
                            position="absolute"
                            top="0"
                            left="0"
                            right="0"
                            bottom="0"
                            bg="white"
                            zIndex={0} // Content will be behind the inbox
                            padding="20px"
                            display="flex"
                            flexDirection="column"
                            alignItems="center"
                            justifyContent="center"
                            textAlign="center"
                            overflowY="auto" // Allow scrolling if content exceeds viewport
                        >
                            <Heading color="gray.600">
                                Notion Inbox Notification Theme
                            </Heading>
                            <Text fontSize="lg" color="gray.500" mt="4">
                                Checkout the deployed version now
                            </Text>
                            <Button
                                mt="8"
                                colorScheme="blue"
                                onClick={() => window.open('https://inbox.novu.co/', '_blank')}
                            >
                                Visit Playground
                            </Button>
                        </Box>

                        {/* Inbox Popover */}
                        {isInboxOpen && (
                            <Box
                                height="100%"
                                bg="white"
                                overflowY="auto"
                                width="100%"
                                maxW="390px"
                                zIndex={1}
                                boxShadow={
                                    "rgba(15, 15, 15, 0.04) 0px 0px 0px 1px, rgba(15, 15, 15, 0.03) 0px 3px 6px, rgba(15, 15, 15, 0.06) 0px 9px 24px"
                                }
                            >
                                <Inbox
                                    subscriberId={subscriberId as string}
                                    applicationIdentifier={applicationIdentifier as string}
                                >
                                    <Notifications
                                        renderNotification={(notification) => (
                                            <InboxItem notification={notification} />
                                        )}
                                    />
                                </Inbox>

                            </Box>
                        )}
                    </Box>
                </Flex>
            </Box>
        </Flex>
    );
};

// Sidebar Item Component
interface SidebarItemProps {
    icon: React.ElementType;
    label: string;
    isActive?: boolean;
    external?: boolean;
    onClick?: () => void;
}

const SidebarItem: React.FC<SidebarItemProps> = ({
    icon,
    label,
    isActive = false,
    external = false,
    onClick,
}) => {
    return (
        <HStack
            as={external ? Link : Box}
            spacing={3}
            p={2}
            fontWeight="500"
            borderRadius="6px"
            bg={isActive ? "rgba(0, 0, 0, 0.03)" : "transparent"}
            color={isActive ? "rgb(29, 27, 22)" : "rgba(55, 53, 47, 0.65)"}
            _hover={{ bg: "rgba(0, 0, 0, 0.03)", cursor: "pointer" }}
            sx={{
                height: "28px",
                padding: "4px 8px",
            }}
            onClick={onClick}
        >
            <Icon
                sx={{
                    width: "20px",
                    height: "20px",
                }}
                as={icon}
            />
            <Text fontSize="14px">{label}</Text>
        </HStack>
    );
};

const InboxItem = ({ notification }: { notification: Notification }) => {
    const [isHovered, setIsHovered] = useState(false);
    const notificationType = notification.tags?.[0];

    return (
        <Box
            p={2}
            bg="white"
            position="relative"
            onMouseEnter={() => setIsHovered(true)}
            onMouseLeave={() => setIsHovered(false)}
        >
            <Flex align="flex-start" position="relative">
                <VStack spacing={0} position="absolute" top="0" right="0">
                    {isHovered && (
                        <Box bg="white" display="flex" gap={1}>
                            {notification.isRead ? (
                                <IconButton
                                    aria-label="Mark as unread"
                                    icon={<PiNotificationFill />}
                                    onClick={() => notification.unread()}
                                    size="sm"
                                    variant="ghost"
                                />
                            ) : (
                                <IconButton
                                    aria-label="Mark as read"
                                    icon={<FaRegCheckSquare />}
                                    onClick={() => notification.read()}
                                    size="sm"
                                    variant="ghost"
                                />
                            )}
                            {notification.isArchived ? (
                                <IconButton
                                    aria-label="Unarchive"
                                    icon={<PiNotificationFill />}
                                    onClick={() => notification.unarchive()}
                                    size="sm"
                                    variant="ghost"
                                />
                            ) : (
                                <IconButton
                                    aria-label="Archive"
                                    icon={<FiArchive />}
                                    onClick={() => notification.archive()}
                                    size="sm"
                                    variant="ghost"
                                />
                            )}
                        </Box>
                    )}
                </VStack>

                <Box
                    position="relative"
                    display="flex"
                    alignItems="center"
                    mr="8px"
                    height="26px"
                >
                    {!notification.isRead && (
                        <Box>
                            <Box width="8px" height="8px" bg="blue.500" borderRadius="full" />
                        </Box>
                    )}
                    {notification.avatar !== undefined && (
                        <Avatar
                            width="24px"
                            height="24px"
                            marginLeft="8px"
                            name={notification.to.firstName}
                            src={notification.avatar || undefined}
                        />
                    )}
                </Box>

                <VStack align="start" spacing="8px" flex="1" mt="3px">
                    <Flex justify="space-between" width="100%">
                        <Text fontSize="14px" color="gray.800" fontWeight="600">
                            {notification.subject}
                        </Text>
                        <Text fontSize="xs" color="gray.400">
                            {formatTime(notification.createdAt)}
                        </Text>
                    </Flex>

                    {notificationType !== "Mention" &&
                        notificationType !== "Comment" &&
                        notificationType !== "Invite" && (
                            <Text fontSize="14px" color="gray.800">
                                {notification.body}
                            </Text>
                        )}

                    {(notificationType === "Mention" ||
                        notificationType === "Comment") && (
                            <Button
                                variant="ghost"
                                size="sm"
                                leftIcon={<GrDocumentText />}
                                _hover={{ bg: "rgba(0, 0, 0, 0.03)" }}
                                pl="2px"
                                pr="5px"
                                height="25px"
                            >
                                <Text
                                    fontSize="14px"
                                    color="gray.800"
                                    fontWeight="500"
                                    backgroundImage="linear-gradient(to right, rgba(55, 53, 47, 0.16) 0%, rgba(55, 53, 47, 0.16) 100%)"
                                    backgroundRepeat="repeat-x"
                                    backgroundSize="100% 1px"
                                    backgroundPosition="0 100%"
                                    mr="-2px"
                                >
                                    {notification.body}
                                </Text>
                            </Button>
                        )}

                    {notificationType === "Invite" && (
                        <Button
                            variant="outline"
                            size="md"
                            _hover={{ bg: "rgba(0, 0, 0, 0.03)" }}
                            padding="12px"
                            height="50px"
                            fontSize="14px"
                            width="100%"
                            borderRadius="8px"
                            textAlign="left"
                            border="1px solid rgba(227, 226, 224, 0.5)"
                            justifyContent="space-between"
                        >
                            {notification.body}
                        </Button>
                    )}

                    {notificationType === "Comment" && (
                        <Box>
                            <Text fontSize="12px" color="rgb(120, 119, 116)" fontWeight="400">
                                John Doe
                            </Text>
                            <Text fontSize="14px" color="rgb(55, 53, 47)" fontWeight="400">
                                This is a notification Comment made by John Doe and posted on
                                the page Top Secret Project
                            </Text>
                        </Box>
                    )}

                    <HStack spacing={3}>
                        {notification.primaryAction && (
                            <Button
                                variant="outline"
                                size="xs"
                                colorScheme="gray"
                                borderRadius="md"
                                borderColor="gray.300"
                                _hover={{ bg: "gray.100" }}
                                paddingRight="8px"
                                paddingLeft="8px"
                                lineHeight="26px"
                                height="26px"
                            >
                                {notification.primaryAction.label}
                            </Button>
                        )}
                        {notification.secondaryAction && (
                            <Button
                                variant="ghost"
                                size="xs"
                                colorScheme="gray"
                                borderRadius="md"
                                borderColor="gray.300"
                                _hover={{ bg: "gray.100" }}
                                paddingRight="8px"
                                paddingLeft="8px"
                                lineHeight="26px"
                                height="26px"
                            >
                                {notification.secondaryAction.label}
                            </Button>
                        )}
                    </HStack>
                </VStack>
            </Flex>
        </Box>
    );
};

function formatTime(timestamp: number | string | Date): string {
    const date = new Date(timestamp);
    const now = new Date();
    const diffInSeconds = Math.floor((now.getTime() - date.getTime()) / 1000);
    const secondsInMinute = 60;
    const secondsInHour = secondsInMinute * 60;
    const secondsInDay = secondsInHour * 24;
    const secondsInWeek = secondsInDay * 7;
    const secondsInYear = secondsInDay * 365;

    if (diffInSeconds < secondsInMinute) {
        return `${diffInSeconds} seconds`;
    } else if (diffInSeconds < secondsInHour) {
        const minutes = Math.floor(diffInSeconds / secondsInMinute);
        return `${minutes} minute${minutes !== 1 ? 's' : ''}`;
    } else if (diffInSeconds < secondsInDay) {
        const hours = Math.floor(diffInSeconds / secondsInHour);
        return `${hours} hour${hours !== 1 ? 's' : ''}`;
    } else if (diffInSeconds < secondsInWeek) {
        const days = Math.floor(diffInSeconds / secondsInDay);
        return `${days} day${days !== 1 ? 's' : ''}`;
    } else if (diffInSeconds < secondsInYear) {
        const options: Intl.DateTimeFormatOptions = { month: "short", day: "numeric" };
        return date.toLocaleDateString(undefined, options);
    } else {
        return date.getFullYear().toString();
    }
}

export default AppContainer;

Ready to get customizing? Here’s the source code for the Notion Inbox theme. You can also see and play with it live in our Inbox playground. I also did the same for a Reddit notifications example. Two totally different experiences, but powered by the same underlying component and notifications infrastructure.

Build a Real-time Notification System with Socket.IO and ReactJS

Emil Pearce — Wed, 02 Oct 2024 18:14:17 +0000

Building real-time notifications is complex. You need a solid infrastructure that supports real-time data delivery, ensuring instant and reliable notifications, even with high user activity. This requires scalable backend systems and efficient communication protocols like WebSockets or push notifications to maintain low latency. For admins in chat rooms or similar environments, timely monitoring of room activities requires setting up an email notification system that alerts them about key events or issues in chat rooms, which adds to the overall challenge.

This tutorial will guide you through building a real-time notification system for a chat app using React and Socket.io. React is ideal for creating dynamic, reusable components and efficiently managing your app’s state. Socket.io enables real-time, bidirectional communication between the server and the browser, allowing instant message delivery without page reloads. This combination lets you build a responsive, interactive UI that communicates with the server in real-time.

We’ll deliver real-time email notifications with Novu.

Prerequisites

Before we dive into the tutorial, make sure you have the following:

Node.js - installed on the computer, allows us to run JavaScript code outside a web browser.
Socket.io - for seamless communication between the React frontend and the server

With these prerequisites in place, we're ready to start building the real-time application. Want to see the complete code? Check it out on GitHub. Now, let’s proceed with setting up the development environment.

Setting up the development environment

First, open up the terminal, navigate to a desired directory, and run the following commands:

mkdir realtime-chat-app
cd realtime-chat-app
npm init --y

The commands above create a new directory called “realtime-chat-app.” Once that’s set up, it’s time to initialize the project. Inside the directory, run npm init to start a new npm project. The —y flags select the default values of all the prompts.

Installing dependencies

Now that the project is ready, it’s time to install the necessary dependencies. Still in the "realtime-chat-app" directory, run the command below to install all the dependencies required to set up the backend server.

npm install Express socket.io @novu/node cors nodemon

The above command will install the following npm packages:

Express - a flexible foundation for building our Node.js backend server.
socket.io - for seamless communication between the React frontend and the server.
cors - to enable secure communication by managing access control for cross-origin requests.
nodemon - automatically restarts our Node.js server whenever we make changes to the codebase

With the required dependencies installed, it’s time to create the index.js file. As specified in package.json, this file will serve as the entry point for the backend server. From here, the core of the backend starts coming together.

Building the backend server with Express

To initialize the backend server, import the required modules into the index.js file and instantiate an Express application with the following code:

    const Express = require("Express");
    const http = require("http");
    const cors = require("cors");

    const app = Express();
    app.use(cors());
    const PORT = 3001;


    server.listen(PORT, () => {
      log(`server running on ${PORT}`);
    });

Here, an Express application instance is initialized using Express(), and the cors() middleware is applied to the app to allow requests from different origins. The PORT constant specifies the server's listening port.

To initiate the Express server, modify the package.json script with the following code:

"start": "nodemon index.js"

Running npm start launches the server at http://localhost:3001. With that, the Express setup is completed; now, let's integrate Socket.IO into the server.

Integrating Socket.IO into the server

First, import Socket.IO and Novu modules inside the index.js file with the following lines of code:

    #index.js
    const { server } = require("socket.io");
    const { Novu } = require("@novu/node");

The next thing is to create a Socket.IO connection. Update the index.js with the following snippet:

    #index.js

    const io = new server(server, {
      cors: {
        origin: "http://localhost:3000",
        methods: ["GET", "POST"],
      },
    });

The snippet above creates a new instance of the Socket.IO server and specifies the origin of the connections that are allowed. In this case, it's http://localhost:3000 because that is the port the React.js framework will run on. This code also defines the allowed HTTP methods for requests. Now it's time to create some events.

Handling Socket.IO events on the server

The first event to set up is the "connection" event, which fires whenever a user visits the application. This event helps us track when users are connected to the server. Let’s add it to the index.js file along with some additional events to manage user actions:

    #index.js 
    io.on("connection", (socket) => {
      console.log(`User connected ${socket.id}`);

    // Event for when a user joins a room
      socket.on("join_room", (data) => {
        socket.join(data.room);
        console.log(data);
      });

    // Event for when a user sends a message
      socket.on("send_message", (data) => {
      console.log(data.message);
      });

    // Event for when a user disconnects
      socket.on("disconnect", () =>console.log("User disconnected", socket.id));
    });

The "join_room" event fires when a user has joined a room (like a chat group). The "send_message" event will fire when a user sends a message, while the "disconnect" event runs when the user leaves or refreshes the application.

The data passed through the "join_room" and "send_message" events will come from the React application. Now that we have created the server-side event handlers, let's create the React application and see how it will interact with these events and communicate with the Socket.IO server.

Building the frontend with React

To get started, open the terminal and run the following command to generate a new React application within a directory named "client":

npx create-react-app client

The next step is equipping our React application with the tools for real-time communication and user interaction. Add the following package:

socket.io-client: This will enable the React application to connect to the Socket.IO server we created earlier.

Navigate to the React project directory (client) in the terminal and run the following command:

npm install socket.io

With the project setup completed, navigate to the src folder within our React project. In the next section, we'll set up the Socket.IO client to establish real-time communication with the backend server and develop the user interface component to handle user input.

Connecting React to the server and emitting events

Let's connect the React app to the backend server and listen to the Socket.IO event we created earlier. Clean up the src/App.js file and add the following snippets:

    #client/src/App.js
    import "./App.css";
    import io from "socket.io-client";
    import { useState } from "react";

    const socket = io.connect("http://localhost:3001");

    function App() {
      const [username, setUsername] = useState("");
      const [room, setRoom] = useState("");
      const [userEmail, setUserEmail] = useState("");

    const joinRoom = () => {
        if (username !== "" && room !== "") {
          const userDetails = {
            username: username,
            email: userEmail,
            room: room,
          };
          socket.emit("join_room", userDetails);
        }
      };
      return (
        <div className="App">
          <div className="joinChatContainer">
            <h3>Join Room</h3>
            <input
              type="text"
              value={username}
              placeholder="Name"
              onChange={(e) => setUsername(e.target.value)}
            />
            <input
                type="email"
                placeholder="Email"
                required
                value={userEmail}
                onChange={(e) => setUserEmail(e.target.value)}
              />
            <input
              type="text"
              placeholder="Room"
              value={room}
              onChange={(e) => setRoom(e.target.value)}
            />
            <button onClick={joinRoom}>Join</button>
          </div>
        </div>
      );
    }
    export default App;

In the above snippet, the socket constant establishes a connection to the Socket.IO server running on http://localhost:3001.

The joinRoom function validates that both username and room are provided. If valid, it creates a userDetails object containing the information and then emits a "join_room" event to the server, sending the userDetails object for further processing. Start the react application, and in the browser, it should look like the image below:

After providing the username and desired room, click the Join button. The console will display the submitted details as the 'join_room' event logs the user information.

Now that we’ve successfully emitted and handled an event from React on the server, it's time to build a chat room component to demonstrate real-time interactions between users in the same room.

Implementing real-time features

To showcase real-time communication, let’s create a dynamic chat room component. In the src folder within the React project, create a new file named Chat.js. Within this file, add the following code snippets:

    #client/src/Chat.js
    import { useEffect, useState } from "react";
    import ScrollToBottom from "react-scroll-to-bottom";

    function Chat({ socket, username, room, email }) {
      const [currentMsg, setCurretMsg] = useState("");
      const [messages, setMessages] = useState([]);

    const sendMessage = async () => {
        if (currentMsg !== "") {
          const messageBody = {
            id: socket.id,
            room: room,
            email: email,
            sender: username,
            message: currentMsg,
            time:
              new Date(Date.now()).getHours() +
              ":" +
              new Date(Date.now()).getMinutes(),
          };
          await socket.emit("send_message", messageBody);
          setMessages((list) => [...list, messageBody]);
          setCurretMsg("");
        }
      };

      return ();
    }
    export default Chat;

The snippet above does the following:

It uses useState from React to manage two state variables:
- currentMsg: Stores the user's current message draft.
- messages: Maintains an array of all messages displayed in the chat component.
The sendMessage function handles sending messages. It first checks if a message is written. If there is a message, it creates a messageBody object containing sender details, message content, and a timestamp.
It then emits the "send_message" event to the server, sending the message data.

Rendering the chat component's UI

In order to render the user interface elements. Add the following snippet to the return() function of the Chat.js component:

    #client/src/Chat.js

        <div className="chat-window">
          <div className="">
            <p>Live Chat</p>
          </div>
          <div className="chat-body">
              {messages &&
                messages.map((msg) => {
                  return (
                    <div
                      className="message"
                      id={username === msg.sender ? "you" : "other"}
                    >
                      <div>
                        <div className="message-content">
                          <p>{msg.message}</p>
                        </div>
                        <div className="message-meta">
                          <p id="time">{msg.time}</p>
                          <p id="sender">{msg.sender}</p>
                        </div>
                      </div>
                    </div>
                  );
                })}
          </div>
          <div className="chat-footer">
            <input
              type="text"
              placeholder="Hey..."
              onChange={(e) => setCurretMsg(e.target.value)}
            />
            <button onClick={sendMessage}>&#9658;</button>
          </div>
        </div>

The code above builds the Chat component's UI. It creates a chat window with a header, body, and footer.

The body will display chat history, while the footer contains an input field for composing messages and a button to trigger the sendMessage function.

Next, import and render the Chat.js component inside the App.js file and update the
App.js file with the following code snippet:

    #client/src/App.js
    // other imports
    import Chat from "./Chat";

    const socket = io.connect("http://localhost:3001");

    function App() {
      // other state constants here
      const [showChatBox, setShowChatBox] = useState(false);
      const joinRoom = () => {
        if (username !== "" && room !== "") {
          //userDetails object  here
          socket.emit("join_room", userDetails);
          setShowChatBox(true);
        }
      };
      return (
        <div className="App">
          {!showChatBox ? (
            <div className="joinChatContainer">
              <h3>Join Chat</h3>
              {/* username and room inputs here */}
              {/* Join button here */}
            </div>
          ) : (
            <Chat socket={socket} username={username} room={room} />
          )}
        </div>
      );
    }
    export default App;

The Chat.js component was imported and conditionally rendered to display the chat interface dynamically based on the showChatBox state variable. Upon successfully joining a room, users will be welcomed with an interactive chat interface that resembles the following visual:

The dynamic rendering ensures that the chat component is only visible when a user has joined a room, providing an intuitive user experience.

Next, let’s go to the backend server and process the message data sent by users. Within the “send_message” event, add this line of code:

    socket.to(data.room).emit("recieve_message", data);

The code above does the following:

**socket.to(data.room)** - targets a specific room on the server. It uses the data.room property extracted from the received message object. This ensures that messages are only sent to users in the same room.
Meanwhile, .emit("recieve_message", data) emits the "recieve_message" event and reroutes the received message data (data) to all the users in the same room.

Handling incoming messages

Let's implement the logic to listen to the "receive_message" event and dynamically update the chat interface with the incoming messages. In the Chat.js component after the sendMessage() function, add the following code snippet:

    #client/src/Chat.js
     useEffect(() => {
        socket.on("recieve_message", (data) => {
          setMessages((list) => [...list, data]);
        });
      }, [socket]);

Here, the useEffect hook constantly monitors incoming messages. It establishes a callback function that executes whenever the "receive_message" event is triggered by the Socket.IO server.

Within this callback, the setMessages function updates the messages state. Using the spread operator, the incoming message (data) is appended to the existing list of messages.

This update triggers a re-render of the chat component, ensuring the new message is instantly displayed in the chat window for all users in the same room.

With that, we've just built a fully functional chat application using Socket.IO and React. To enhance user experience even further, let’s implement some real-time notification features like:
Room join alerts: Socket.IO allows us to emit a custom event (e.g., "user_joined") from the server whenever a new user joins a room. We can then listen to the event and update the chat interface accordingly.

Real-time room join alerts
To implement the real-time room join alerts, navigate back to the server (index.js) and update the “join_room” event with the following snippet:

    socket.to(data.room).emit("user_joined", data);

The snippet above does the following:

socket.to(data.room) extracts the data.room property from the newly joined user's information and assures that the notification is only broadcasted to users within the same room as the new member.
.emit("user_joined," data) emits a custom event named "user_joined" to all connected clients (sockets) within the designated room using socket.to. It transmits the received user data (data) along with the event.

Next, we’ll listen to the "user_joined" event in our React application and display a notification to reflect the new member's presence. Head over to client/src/App.js file and modify the joinRoom() like the below:

    #client/src/App.js
      const joinRoom = () => {
        if (username !== "" && room !== "") {
          const userDetails = {
            username: username,
            room: room,
          };
          socket.emit("join_room", userDetails);
          socket.on("user_joined", (data) => {
            alert(`${data.username} joined the room`);
          });
          setShowChatBox(true);
        }
      };

Now, whenever a new user joins a room, the server immediately broadcasts a custom event ("user_joined") to all existing users within that same room.

To enhance the user experience even further and keep administrators informed, let's add Novu email notification to the application. Novu is a notification platform that simplifies the process of sending and managing notifications within applications. By setting up Novu to send email alerts to inactive users, you can stay updated on room activity and ensure timely intervention.

Novu email notifications
In this section, we’ll use Novu to send friendly reminders to users who haven't been active in the chat for a while as long as they're still connected to the app.

To access Novu services, first create an account. Then, navigate to Workflows > demo-recent-login > send-email to see a sample of the email that will be sent. We can modify the step controls and payload to match our requirements.

Navigate to the left side of the dashboard, as shown above, to copy your secret key to the "API Keys." In the terminal, install @novu/node packages to help communicate with Novu, and trigger real-time notifications within the Node.js server.

npm install @novu/node

Within the chat application's root directory, create a file named .env and add the following line of code, replacing "YOUR NOVU SECRET KEY" with the actual Novu secret key we copied earlier:

#.env
NOVU_SECRET_KEY ="Paste your secret key here"

Inside the Chat.js file within the src directory, add the following snippet after the sendMessage() function:

    //src/Chat.js
      const activeChat = () => {
        if (document.hidden) {
          const payload = {
            id: socket.id,
            room: room,
            sender: username,
            email: email,
          };
          socket.emit("notify-user", payload);
        }
      };
      setInterval(() => {
        activeChat();
      }, 300000);

The snippet above checks if the user's Chat window is inactive (document.hidden) and, if so, sends a "notify-user" message to the server every 300 seconds (using setInterval). The message contains the user's ID, email, and other details.

Next, in the index.js file, import the Novu module with the following line of code:

    #index.js
    import { Novu } from '@novu/node';

Then add the following snippet after the Socket.IO initialization in the server(index.js):

    #index.js
    const time = new Date();
    const novu = new Novu(process.env.NOVU_SECRET_KEY);
    const notification = (data) => {
      novu.trigger("demo-recent-login", {
        to: {
          subscriberId: "66be2642d3f9eb69fff3f2ca",
          email: data.email,
        },
       payload: {
          header: `Hi ${data.sender} you have an active chat at room ${data.room} login to continue chatting`,
          loginDate: JSON.parse(JSON.stringify(time)),
          loginLocation: "Unknown",
          userFirstName: data.username,
        },
      });
    };

The snippet above demonstrates how to trigger an email notification at a specific interval:

The novu.trigger method is called inside the notification() function, specifying the workflow name ("demo-recent-login") and the notification data.
The to object defines the recipient details, including their subscriber ID and email address.
The payload object defines the content of the email notification, including a personalized header, timestamp, and username.

The placeholder value for the subscriber ID can be replaced with the actual value.

In the server, after the “user_joined” event, listen for the “notify-user” event; call the notification() function and pass the data property:

    socket.on("notify-user", (data) => {
        notification(data);
      });

Now, whenever the server receives a "notify-user" event, it invokes the notification() function, passing the user's data as input. This triggers the email notification process, sending a reminder to the user’s email address.

Novu provides extensive customization options to fine-tune the notifications. Explore the Novu documentation for detailed guidance on tailoring notification settings to specific needs.

Yes! We've built an awesome real-time chat app. Thanks to Novu, users can connect and chat, and admins even get notified via email. But before we call it a wrap, there's one important step—to ensure everything works as expected.

Think of it like this: We've built a beautiful car, but before we hit the track, we need to test the engine, check the tires, and make sure everything works. Debugging and testing are like taking the chat app for a spin—they’ll help us identify errors and fix them for an excellent user experience.

Debugging and error handling

Building a real-time chat app with Socket.IO and React is awesome, but sometimes, things don't go as planned. Here are the common bumps we might encounter and how to fix them:

Common issues and fixes
When working with Socket.IO and React, the following issues can occur:

Can't connect - Make sure that the Socket.IO server is up and running at the URL specified in our React app.
Events not firing - Double-check the event names on the server and client sides. A typo or a case-sensitive mistake can block communication.
Data is inaccurate - Ensure the data sent through Socket.IO events is formatted correctly (like JSON).
UI not updating - Make sure that the React components listen to the right Socket.IO events and update the UI state accordingly. React DevTools helps us identify issues related to rendering or keeping the app's state in sync.

By anticipating these challenges, we can proactively address them, preventing potential issues and implementing practical solutions.

Debugging techniques in Socket.IO

Having a smooth chat experience depends on the Socket.IO server running perfectly. Here are some techniques we can use to sniff out any bugs:

Server-side logging: Use a logging library like Winston. It keeps track of everything happening on the server – connections, events, and errors.
Console logging: Implement log statements throughout the server code to inspect data flow, event triggers, and state changes. This allows us to trace the execution path and identify unexpected behavior.
Network traffic inspection: Use the browser's developer tools to spy on network traffic and confirm if connections are made, data is sent, and the server responds properly.

By adopting these techniques, we'll understand what's happening on the server and fix any problems that might stop our chat app from working perfectly.

Debugging techniques in React

While building the React application, we'll need to debug UI updates and ensure proper client-side functionality. Here are some effective debugging techniques for React:

Browser developer tools: The first line of defense for debugging React applications is using the browser's built-in developer tools. Tools like Chrome DevTools offer a powerful suite for inspecting the component hierarchy, tracking state changes, and pinpointing errors.
React DevTools: While browser developer tools are great for general debugging, consider installing the React DevTools browser extension for deeper insights specific to React.
Console logging: Similar to the server side, use console.log statements within the React components to inspect data flow, state mutations, and component lifecycle events.
Error handling: Implement proper error handling mechanisms within the React components to catch any exceptions or unexpected behavior. This can be done by displaying user-friendly error messages.

By mastering these techniques, we’ll be equipped to fix any UI glitches and be sure the app displays data perfectly based on real-time updates. Remember to remove those console logs before launching the app.

Remember the beautiful car? We’ve now learned how to debug the engine, check the tires, and fix any errors. It's time to take it for a test drive on different terrains – uphill climbs, sharp turns – to ensure it handles everything users might throw at it.

Testing in Socket.IO and React application

Building a reliable real-time application requires testing strategies to ensure a smooth user experience and robust functionality. Let's discuss different testing approaches to validate the interaction between a Socket.IO and React application:

Unit testing
Unit testing isolates individual components and verifies their behavior in a controlled environment. It can isolate functions responsible for processing data received through Socket.IO events, ensuring that data manipulation and state updates happen as expected.

Jest and React Testing Library are popular tools used to test React applications. These libraries provide tools for mocking dependencies, simulating user interactions, and asserting the expected behavior of our components.

To conduct a unit test in the real-time chat application we just built, head over to the client/src folder and create a Chat.test.js file with the following snippet:

    #client/src/Chat.test.js
    import "@testing-library/jest-dom";
    import { render, screen } from "@testing-library/react";
    import Chat from "./Chat";
    // Mock the Socket.IO functionality
    jest.mock("socket.io-client");
    test("renders received messages", () => {
      const mockMessages = [
        { message: "Live Chat", sender: "user1", time: "10:20" },
      ];
      const mockSocket = { on: jest.fn() };
      // Render the Chat component with mocked props
      render(
        <Chat
          socket={mockSocket}
          username="test_user"
          room="5"
          messages={mockMessages}
        />
      );
      // Verify message rendering
      const message = screen.getByText("Live Chat");
      expect(message).toBeInTheDocument();
      // Simulate receiving a new message through the socket
      mockSocket.on.mock.calls\[0\][1]({
        message: "New message!",
        sender: "user2",
        time: "10:21",
      });
      // Verify new message rendering after receiving it through the socket
      const newMessage = screen.getByText("New message!");
      expect(newMessage).toBeInTheDocument();
    });

The test here ensures that the chat component in our React application displays received messages correctly. In addition, it does the following:

It mocks the socket connection to avoid actual network calls during the test.
The test simulates sending initial messages and a new message through the socket.
The chat component is rendered with these mocked messages and a mock socket object.
The test then verifies if the initial messages appear on the screen.
Finally, it simulates a new message being received and checks if it's also displayed correctly.

Integration testing

Integration testing focuses on how different parts of our application interact with each other.
Implementing integration tests makes us confident that the application's components and functionalities work together when dealing with real-time data exchange.

End-to-End testing
End-to-end testing recreates fundamental user interactions with the application. It involves testing the flow from user actions in the React client to data processing on the server and subsequent updates through Socket.IO.

To implement end-to-end testing in our real-time Chat app, use browser automation tools like Cypress to replicate user actions such as joining rooms, sending messages, and receiving updates. This demonstrates the entire flow, from user interaction to real-time updates in the UI.

We've put our chat app through its paces with various testing approaches. Let's discuss some best practices to keep the Socket.IO and React integration running smoothly.

Best practices for Socket.IO and React integration

Here's a breakdown of best practices to guarantee a smooth user experience and a robust architecture when integrating Socket.IO in a React application:

Optimizing performance

Minimizing data: When sending messages, focus on the essentials. Use JSON and choose simple data types (numbers and strings) to keep things moving fast.
Event throttling: If the application sends frequent updates, consider throttling them to avoid overwhelming the server and client.
Caching: Caching frequently accessed data on both the server and client can improve performance by reducing redundant database queries and network requests.

Ensuring security

Authentication and authorization: Implement authentication and authorization to keep out unauthorized users.
Data validation: Always check the format and content of incoming messages, especially for sensitive information. This helps prevent potential security vulnerabilities like data injection attacks.
Event access control: Control which events users can trigger and listen to. This keeps unauthorized users from messing with things they shouldn't. We can also implement role-based controls to grant permissions based on user privileges.

Maintaining scalability

Load balancing: As the app grows, use a load balancer to distribute the work among multiple servers.
Scalable server infrastructure: Consider cloud-based infrastructure to easily scale the server resources up or down as needed. This keeps the app running smoothly even during peak traffic times.
Performance Monitoring: Keep an eye on the app's performance using tools and metrics. Identify what's slowing things down and make adjustments.

By following these key best practices, the Socket.IO and React application will deliver a fantastic user experience, robust security, and scalable architecture to handle anything thrown at it.

Summary

We've learned to build a real-time chat application using ReactJS and Socket.IO, including setting up the backend with Express and integrating real-time front-end features. We've also seen how integrating Novu enhances the application with real-time notifications, informing admins about user activities.

But we can take it further by allowing users to receive notifications about new messages even when they're not actively using the app. Novu’s notification system also offers customizable alerts and supports various channels, from email to SMS, push notifications, etc., ensuring users stay engaged and up-to-date with minimal effort. Sign up on Novu today and start sending personalized alerts and emails.

The Full-Stack Components Customization Pyramid

Dima Grossman — Wed, 18 Sep 2024 12:50:39 +0000

Component Anatomy
The Customization Pyramid
Appearance Prop
Render props
Composition
React Hooks
Conclusion

A while back, I came across a tweet by Colin from Clerk.com stating that "Components are the new API." I couldn't agree more. For years, we've been dedicated to building embeddable components for our customers. The objective is straightforward: How can we create a fully functional component that feels so integrated and seamless that it appears to be built in-house by the host application?

Previously, a common pattern for embedding components using controllable iframes led to inconsistent behavior and, in many cases, was felt disconnected. The rise of the meta frameworks and the serverless motion provided an easier paradigm to embed native to the framework components that are one with the host application.

You've probably encountered numerous examples already: Stripe, Clerk, Liveblocks, Algolia, and others.

Component anatomy

All of the successful components I’ve interacted with showcased the following characteristics:

First-class User Experience (UX): It felt like a dedicated team crafted the component just for my application
Amazing Developer Experience (DX): It was intuitive and easy to get started within minutes
Customizability: It could seamlessly blend into my host application, but still provided a strong opinion
Lightweight bundle size: It was efficient and minimal in size
Common framework: The component was available in the framework I used in my app

Did I miss anything you think is important? Share your observations in the comments section.

In this article, we will focus on component customization and styling. I'll share some lessons we learned while building the new Novu <Inbox /> component and how we approached meeting our customers' needs.

The customization pyramid

Customization and styling exist on a spectrum between more control and less control. Whether you are just starting out and want to get up and running quickly, or you are a Fortune 500 company with a strict design system, a team of designers, and complex requirements, you should always be able to achieve your goals in the least amount of time and still have an amazing developer experience.

Let's explore the customization pyramid concept using Novu’s new <Inbox /> component as an example. By the way, our source code is open-source and publicly available in the Novu GitHub Repository.

Finally, we’ve also made our Figma design asset file publicly available, too.

Appearance Prop

You can think of the appearance prop as a white-labeled internal to the component UI system, that allows styling and modifying different aspects of the component.

A component should be opinionated and render a beautifully crafted UI out of the box. For Novu’s <Inbox /> component, it's as simple as rendering <Inbox /> in your application. Instantly, you get a fully functional UI with a bell icon that opens a popover implementation.

The first thing we might want to do is to make sure that our brand colors and design guidelines are matched within the component. This is where the appearance prop comes into play

<Inbox appereance={{
    variables: {
        primaryColor: 'pink',
        borderRadius: '4px'
    },
    elements: {
        notificationSubject: {
            marginBottom: '5px'
        },
        notificationPrimaryAction__button {
            lineHeight: '18px'
        }
    }
}} />

Variables

These are the variables that apply to all major elements in the UI. Adjusting just a few of these should allow the component to immediately adopt the look and feel of the host application. Variables for typography, colors, and spacing should be included here.

Elements

This section provides more in-depth control over visible elements within the component. At Novu, we namespace components as follows:

notificationSubject
notificationBody
notificationPrimaryAction
notificationPrimaryAction__button
- For sub-elements, we use an underscore notation to namespace repeated components such as buttons and labels.

Customers should be able to choose their preferred styling framework, whether it's Tailwind, CSS Modules, or plain CSS, and it should work seamlessly out of the box.

🌟 Tip: We've added a 🔔 icon to the class name list to help identify the element names. Everything before this emoji can be targeted and styled easily using the elements field.

Render props

In some use cases, styling with CSS alone isn't sufficient. For example, in our world, customers might want to render their own custom notification item components, enrich them with live data, or reuse existing UI elements as part of the notification flow.

Here's how this can look:

<Inbox renderNotification={(notification) => <CustomersCustomItem />} />

This approach provides significantly more control over the look, feel, and behavior of the notifications while still abstracting away the complexities of layouts, real-time updates, fetching, and notification settings.

Composition

While your components should be opinionated, you should not limit your customers to achieving their end goal of implementation. In some cases, you cannot predict the UX pattern they want to use that fits the specifics of their business.

There is a huge gap that sits between a “headless” mode, where you have to build everything from scratch, and the one-liner component that abstracts away pretty much all the internals. Compostable sub-components should bridge this gap, by breaking the one-liner into multiple components that can be re-organized to match different UX patterns.

To facilitate this, your components should be composable. Break down the component structure into independent elements, each focusing on a single goal. In our example:

<Bell />
<Notifications />
<Preferences />
<Inbox />

Each element can be rendered as a standalone component and combined to create various layouts, still abstracting away complexity.

React Hooks

When customers have strict design and UX requirements, using React Hooks are invaluable. However, resorting to a headless approach like this sometimes indicates a failure to provide adequate styling and composition options, or potentially a framework-specific SDK. To better understand the reasoning, we engage with customers who choose this route to understand if their use case can benefit others.

The React Hooks headless SDK allows customers to build any UI they want, managing the look and feel, state, interactions, and layout themselves.

Here's an example:

import { Novu } from "@novu/js";

const novu = new Novu({
    subscriberId: "SUBSCRIBER_ID",
    applicationIdentifier: "APPLICATION_IDENTIFIER",
});

const notifications = await novu.notifications.list({
    limit: 30,
});

novu.on("notifications.notification_received", (data) => {
    console.log("new notification =>", data);
});

The headless SDK provides no UI but offers a straightforward set of wrappers around your component's most common API and server actions.

Conclusion

Thinking from the perspective of your users and setting up the right architecture in the beginning will go a long way. Invest the time debating DX, show this to your users, and try to understand the main friction points in their adoption. Lastly, think of your customization strategy in layers to allow your customers to start fast and not block them if they have more specific styling and UX requirements.

I’m curious to see where the future of “Components are the new API” will take us as a team, and I'm looking forward to learning from our amazing community.

Finally, I’d be remiss if I didn’t tell you to take a look at our result. Here, you’ll find a fully functional <Inbox /> playground we styled to mimic popular apps (Notion and Reddit), and then you can also experiment by customizing your own.

Dima GrossmanFollow

Musician, Baker, and Maker. Creator of Novu - The open-source notification infrastructure for engineers.

Building Open Source React Components for Real-Time Notifications

Emil Pearce — Wed, 14 Aug 2024 15:36:13 +0000

TL;DR

Components are the new API. If you’re a modern stack web developer—meaning you’re working in the JavaScript ecosystem, and either use components, or are creating your own. This is about the latter—how we re-imagined our own <Inbox /> component, and built an all-new set of components. Our new set now is a smaller bundle size, has unparalleled customization and composability, and comprehensive localization support—all designed with developers in mind. Introducing two new SDKs, @novu/js and @novu/react.

Table of Contents

Introduction and Overview
- Linear Inbox
- Notion Inbox & Page Notifications
- Slack Activity Tab
- Ready-To-Use Inbox
Development Rationale
Development Process for the Inbox Component
- Guiding Principles
- Brainstorming and Feature Selection
- Initial Planning
- Design Phase
- Planning and Breaking Down Designs
- Package Development
- UI Framework Research
- CSS Solutions Research
- API Endpoints
- Localization
- Notification Schema Improvement
Comparison
Novu's JavaScript SDK
Novu's React SDK

Introduction and overview

The component is known by many names: Notification Popover, Notification Feed, Notification Center, Activity Feed, Updates Feed, Alert Box, Event Feed, and more.

Its name and function vary depending on the specific use case of the app. At its core, the Inbox component serves as a crucial communication channel between the app and its users.

To make sure we are on the same page, here are few examples:

Linear Inbox

It’s where you receive an Inbox notification for key events on your subscribed issues. You're automatically subscribed to issues when you create them, are assigned them, or are mentioned in an issue description or comment.

(From Linear Docs)

Notion Inbox & Page Notifications

The inbox and notifications in Notion help you stay on top of work that needs your attention, and changes made to the pages and projects you care about. The more people you collaborate with in your workspace, the more helpful these features become.

(From Notion's Help Center)

Slack Activity tab

Use the Activity tab on desktop or mobile to quickly review all of your notifications.
Think of it as a place to focus your attention or to get caught up after some time away from Slack. Click or tap the Activity icon on desktop or mobile to open a chronological feed of your notifications. Select a filter to switch between the different types of notifications, like mentions, replies to threads, or reactions to your messages.

(From Slack's Help Center)

As you can already understand, the scope of an Inbox component could be very narrow or extremely robust, all comes to the app’s use case.

Building real-time event-based updates, messages, and notifications for your app can be highly challenging, especially when factoring in ongoing maintenance and future feature enhancements.

To simplify this process, we’ve developed an open-source, ready-to-use React component that provides an out-of-the-box solution for adding in-app notification capabilities, giving you a head start on your development.

Ready-To-Use Inbox

Here is how the code looks like

import { Inbox } from '@novu/react';

export const novuConfig = {
  applicationIdentifier: 'YOUR_APPLICATION_IDENTIFIER',
  subscriberId: 'YOUR_INTERNAL_SUBSCRIBER_ID',
};

export function Inbox() {
  return (
      <Inbox {...novuConfig} />
  );
}

In this post, we share the “behind-the-scenes” process, providing an in-depth look at WHY and HOW we developed our new components, given that we already had functional ones. I hope you’re able to learn how you can build your own components.

If you prefer to dive right into download and test, jump to this section.

Development rationale

We broke the 1st rule of Programming, “If it works.... don't touch it!”

In May 2022, Novu released the first version of @novu/notification-center; our main repository had around 2K GitHub stars and barely a team of six people; it was a huge milestone for us!

Since then, we've launched numerous features designed to simplify developers' work.

As we build new technology and gain broader exposure, we accumulated valuable insights, feedback, and user requests. These drive us toward innovation, often resulting in the accumulation of technical debt and necessary refactoring.

Breaking down v1 of Novu’s Ul Inbox component collection

React component

The first comprehensive In-App component (@novu/notification-center) was a React library because that is what we knew best.

import {
  NovuProvider,
  PopoverNotificationCenter,
  NotificationBell,
  IMessage,
} from "@novu/notification-center";

function Novu() {
  return (
    <NovuProvider
      subscriberId={"SUBSCRIBER_ID"}
      applicationIdentifier={"APPLICATION_IDENTIFIER"}
    >
      <PopoverNotificationCenter colorScheme="dark">
        {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

The main Notification Center React component had 4 pieces:

NovuProvider - This is a wrapper component that provides the necessary context for Novu's notification center to function. It should be placed at the top level of your application hierarchy.
PopoverNotificationCenter - This is a pre-built component that displays notifications in a popover format.
NotificationBell - This component renders the notification bell icon. It's typically used within the PopoverNotificationCenter and can display the number of unseen notifications.
IMessage - This is an interface type representing a notification message. It contains information about the notification, including its content, status, and any associated actions.

Web component

Novu wanted to cater to all its community members and users. So… The next package wasn’t actually a package; it was another component within @novu/notification-center. We called it “Web Component*”.*

import { NotificationCenterWebComponent } from "@novu/notification-center";

The Notification Center Web Component was a custom element that can be used in any web application. It was built by wrapping the React components and consists from its core the three pieces: NovuProvider, PopoverNotificationCenter, and NotificationBell combined together into one. Our first bundle!

Vue component

The @novu/notification-center-vue package provided a Vue component wrapper over the Notification Center Web Component that you can use to integrate the notification center into your Vue application. The main issue is that it’s using React along with ALL THE DEPENDENCIES under the hood.

Angular component

The @novu/notification-center-angular package provided an
Angular component wrapper over the Notification Center Web Component
that you can use to integrate the notification center into your Angular
application.

iframe embed

If you were using an unsupported client framework, you could use our embedded script. This generated the notification center inside an iframe.

With every new wrapper, time, frequent questions, requests, and issues started to pile up, like:

Very big bundle size
Limitations and general friction in customization and styling.
Many warnings during webpack compile process
“Delete All Notifications” option
Marking a message as "seen" briefly reverts to "unread" during data updates

And more.

We made bug fixes and feature enhancements and even released the @novu/headless, offering a package with just the essential API methods so that users could easily incorporate Novu’s notification system into any framework or vanilla JavaScript project without being constrained by our default UI or dependencies.

With the team expansion, new people started to bring new questions and perspectives to the table.

Development process for the Inbox Component

With the launch of our code (and developer) first code-based @novu/framework workflow approach, we set out to re-evaluate other areas we could make developer’s lives easier. We already believed that components were the answer to drastically reduce the time and complexity required to provide end users a powerful in-app experience. Brainstorming ways we could improve the experience became the next step.

Our straightforward guiding principles

How can we help make it easier for our users to implement an in-app notifications component?
How might we ensure that our users have enough flexibility to deliver the experience they need to provide to their end users?
What can we do to make the developer a hero inside their business?

Brainstorming and feature selection

We started with a brainstorming session to list down the features we wanted in the new Inbox component. After the session, we selected the features to tackle in the first release.

Feature selection

First release: Features for the first release were chosen based on team discussions and planning sessions.
Future versions: Features for future versions are discussed in ongoing planning meetings and are captured on the Linear board and the roadmap.

Design phase

Nikolay, our Product Designer took the requirements and created initial inbox component designs.

Planning and breaking down designs

The team (in this case, Pawel and Biswa) started breaking down the design into smaller pieces to create tickets on Linear.

They conducted several POCs and planning sessions to decide on the packages to create and the framework to use for the UI.

Initial planning

Packages to create
- @novu/js: The foundational package that will be used by other Novu packages such as @novu/react and @novu/vue (in the future).
  
  This package includes everything (headless and UI components).
- @novu/react: Chosen due to React's popularity and significant customer base.

Package development

@novu/js

Headless: API client and Novu classes for custom UIs, replacing the old @novu/headless due to its complexity and unclear documentation.
UI Components: Exporting UI components designed in Figma:
- Inbox: Default all-in-one component.
- Bell: Includes unread count and customizable bell icon.
- Preferences: Full-page list for user settings.
- Notifications: Full-page notifications similar to Twitter's notification feed.

@novu/react

Consumes UI from @novu/js and renders it in React. Each component can be fully replaced by the user’s custom components, offering flexibility and customization.

UI framework research

The team then researched various UI frameworks/libraries, including

SolidJS
React
Vue
Lit
Svelte

They created some POCs with these frameworks and decided on SolidJS due to its lightweight nature, superior performance compared to React, and similar syntax to React, which facilitated ease of adoption.

CSS solutions research

The team researched CSS solutions and customization levels while considering naming conventions for the headless part. Biswa was responsible for researching CSS solutions, and Pawel worked on headless naming conventions.

CSS solutions candidates

vanilla-extract
Panda CSS (Not chosen due to suboptimal experience)
Stitches
Styled-jsx
Linaria
Tailwind
Plain CSS

We chose Tailwind because of compilation to pure CSS classes and better DX.

We aim to provide developers with multiple ways to customize the Novu Inbox component styling.

The available customization options include

Style objects
Classnames
CSS variables
Target classnames

API endpoints

We introduced a new /inbox endpoint path instead of using the existing notification center API due to various changes in the Notification DSL and the need for more straightforward, leaner endpoints.

Our docs won’t publicly expose these endpoints. (We might expose the new endpoints in the future if our users share their needs and use cases). Instead, we encourage our users to use our Component ****SDK and higher-level library UI packages.

A ‹Component/› is worth a thousand APIs

With amazing notification UI components as our primary goal, we realized that Novu wouldn't be a traditional API company. We focused on building a fantastic frontend component SDK, rather than a traditional backend REST SDK.

Components are a higher level of abstraction than REST SDKs. They provide UIs to end-users instead of just functions to developers, so they inherently offer more value.

Localization

Our team mate George worked on Localization. Novu needs to offer a way to override the default copy and localize the content of the <Inbox/> component.

The most intuitive way to do this is via a localization prop.

import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox
      options={{
        subscriberId: 'SUBSCRIBER_ID',
        applicationIdentifier: 'APPLICATION_IDENTIFIER',
      }}
      localization={{
        'inbox.status.archived': 'Archived',
        'inbox.status.unread': 'Unread',
        'inbox.status.options.archived': 'Archived',
        'inbox.status.options.unread': 'Unread',
        'inbox.status.options.unreadRead': 'Unread/Read',
        'inbox.status.unreadRead': 'Unread/Read',
        'inbox.title': 'Inbox',
        'notifications.emptyNotice': 'No notifications',
        locale: 'en-US',
      }}
    />
  );
}

The localization object should remain flat for simplicity and maintainability.

flat

<Inbox localization = {{
    'notification.primaryButtonText': 'Accept',
}}

We might provide localization templates for all languages via a new localization package, or provide a locale prop and localize automatically (could auto-detect too).

Notification schema improvement

We planned to improve the Notification Schema for a better Developer Experience. Biswa created a DX guide for the updated schema and coordinated with Richard from the framework team to ensure alignment.

// ---- EXISTING ENUMS ---- 
enum ChannelTypeEnum {
  IN_APP = 'in_app',
  EMAIL = 'email',
  SMS = 'sms',
  CHAT = 'chat',
  PUSH = 'push',
}
// existing enum
enum ButtonTypeEnum {
  PRIMARY = 'primary',
  SECONDARY = 'secondary',
}
// ------------------------------

// ======== NEW TYPES =======
type Action = {
  label: string;  // Human-readable label for the action.

  isCompleted: boolean; // Indicates whether the action is completed (done/pending)
};

type Subscriber = {
    id: string;
    firstName?: string;
    lastName?: string;
    avatar?: string;
    subscriberId: string;
};

type Redirect = {
     url: string;

     // maybe in V2
     // REF: https://developer.mozilla.org/en-US/docs/Web/API/Window/open#target
     target: '_self' | '_blank' | '_parent' | '_top' | '_unfencedTop';
}

type InboxNotification = {
  id: string;  // Unique identifier for the notification.

  subject?: string;  // Subject/Title of the notification, optional for backward compatibility

  body: string;  // Content/body of the notification.

  to: Subscriber;  // Recipients of the notification.

  read?: boolean;

  archived?: boolean;

  createdAt: string;  // Timestamp indicating when the notification was created.

  readAt?: string;  // Timestamp indicating when the notification was read, optional.

  archivedAt?: string;  // Timestamp indicating when the notification was archived, optional.

  avatar?: string; // The icon URL

  primaryAction?: Action;

  secondaryAction?: Action;

  channelType: ChannelTypeEnum;  // Type of channel through which the notification is sent.

  tags?: string[]; // Array of tags that were applied on the workflow

  redirect?: Redirect;  // URL for performing the redirect on notification click, optional.
}

Notification schema

Defines properties of notification (e.g., subject, content, avatar, read status, archived status) and how it is represented in code and the database. This schema change was also a factor in opting for new endpoints.

Comparison

@novu/notification-center vs. @novu/react

This comparison highlights the differences between the old @novu/notification-center library and the new @novu/react library, emphasizing the improvements and benefits introduced in the new version.

Feature	@novu/notification-center	@novu/react
Component structure	Multiple components (NovuProvider, PopoverNotificationCenter, NotificationBell)	Single All-in-One, and separate dedicated components.
Installation	npm install @novu/notification-center	npm install @novu/react
Setup complexity	Moderate complexity with multiple components	Simplified setup with a single component
Customization	Limited options	Extensive customization options (backend URL, socket URL, state management, localization)
Security	Basic security, requires manual setup for HMAC encryption	Enhanced security with built-in HMAC encryption support
State management	No direct state management for popover	Direct state management via open prop
Localization	Not supported	Supported via localization prop
Real-time updates	Uses useSocket hook for real-time updates	Establishes the single active WebSocket connection that is shared between multiple tabs.
Notification actions	Separate handlers for onNotificationClick and onActionClick	Streamlined handling within the Inbox component
API design	More complex and less intuitive	Simplified and more intuitive
Open source	Yes!	Yes, and now more extensible and community-building.

Wrapping up

Because our goal is to help Novu users implement an in-app inbox, ensure that they have enough flexibility, and make them heroes at their company, we are doubling down on providing the new gold standard in developer tools: UI notification components, starting from our new Inbox component.

And even if frontend developers don't like our components for any reason, they can still build their own UIs without involving a backend developer and a backend SDK.

Once again. we invite you to explore the new @novu/js and @novu/react packages. These tools are designed to make your development process smoother and more efficient.

Novu's JavaScript SDK

Installation

Install @novu/js npm package in your app

npm install @novu/js

Getting started

Add the code below to your application

import { Novu } from '@novu/js';

const novu = new Novu({
  applicationIdentifier: 'YOUR_NOVU_APPLICATION_IDENTIFIER',
  subscriberId: 'YOUR_INTERNAL_SUBSCRIBER_ID',
});

const { data: notifications, error } = await novu.notifications.list();

Novu's React SDK

Installation

Install @novu/react npm package in your app

npm install @novu/react

Getting started

Add the below code in the app.tsx file

import { Inbox } from '@novu/react';

function Novu() {
  return (
    <Inbox
      options={{
        subscriberId: 'SUBSCRIBER_ID',
        applicationIdentifier: 'APPLICATION_IDENTIFIER',
      }}
    />
  );
}

Learn more in our changelog and docs

Liked what you read? Hit follow for more updates and drop a comment below. I’d ❤️ to hear your 💭

Emil PearceFollow

Case Study: How Novu Migrated User Management to Clerk

Emil Pearce — Wed, 31 Jul 2024 16:28:19 +0000

TL;DR

Novu implemented Clerk as a user management solution (Authentication infrastructure) that laid the ground for offering SAML Single Sign-On (SSO) functionality, Google and GitHub as OAuth providers, multi-factor authentication, Role-Based Account Control (RBAC), and more.

One developer named Adam implemented it, with a solid assist from platform engineer Denis.

Like most projects, this one started from the backlog. Not before dozens of customers asked for it, and heavily upvoted the request in our roadmap.

As a notification infrastructure solution, a part of our app and architecture involves managing users from the sign-ups, log-in, and session logs to enable users to invite team members to the organization and manage the access of each role.

It’s all about priorities. Novu’s core focus is to solve all things related to notifications and message management so our users won’t have to. Therefore, we spend our cycles on providing the best experience for building and managing notification workflows, empowering developers to protect their time, and smoothing out collaboration between product and marketing teams.
Effective user management doesn’t fall under that “core value” that we are dedicated to.

In the same way we expect you to offload the burden of engineering notifications to our expertise, we offloaded the burden of engineering effective user management to the expertise of Clerk.

Needless to say, our team built a great authentication and authorization infrastructure in-house from day one, based on custom-tailored and well-designed architecture.

As we level up, we focus even more on perfecting the notification development experience.

We expect developers and engineers to avoid reinventing the wheel and let Novu handle notifications, just as we choose to leverage proven, tested, and leading solutions for other aspects of our product: MongoDB for the database, Stripe for payments, and now Clerk for user management. We walk the talk.

Our primary objective

Create a secure and easy-to-use experience for our users.

When outlining the initial draft for this project, it may appear brief and straightforward, possibly even giving the impression that it could be completed over a weekend.

The initial draft checklist:

OAuth Provider (GitHub, Google)
SAML SSO
Secure session management
RBAC
Magic link auth

Note that if the initial draft hasn’t changed, then the project hasn’t received enough feedback and input. Naturally, the list got longer.

The actual checklist:

Sign up with user credentials
Sign up with OAuth providers (Github, Google)
Sign in with user credentials
Sign in with OAuth providers (Github, Google)
Sign in with SSO (SAML)
Sign in from Novu CLI
Sign in/up from Vercel Marketplace
Create organization
Organization management
User management (update user info, credentials, etc…)
MFA/2FA (OTP via sms/email, TOTP, passkey, biometric, etc.)
Invitations
RBAC: Two roles admin & editor
- admin = The admin can access and interact with any page on the web platform (so, including team members and settings)
- editor = The editor role remains the "main content manager" (aka product manager or marketing manager)

Research and evaluation

After identifying the project's scope, the next step is to conduct research and evaluate the resources needed to achieve the desired outcome.

This process includes:

Have a very clear understanding of the current state and each layer of the product:
- Dependencies
- Endpoints
- Architecture
- Client layer components and representation (frontend)
- Tests
And more.
Outline the migration specs (What remains in-house and should be obstructed away)
Backward compatibility
Try to find references to similar projects, from former colleague maybe, and learn from their process and recommendations
Try and find open-source solutions
Find if there are any vendors (3rd party solutions) and compare them.

And more.

In another blog post, we will explore how we evaluate and compare third-party solutions (or products) as a service/infrastructure as a service company.

Insufficient research or in-accurate evaluation usually leads to technical debt and future losses of resources, such as engineering time when adding additional features and maintenance, which require refactoring of the entire thing. So, search for the hidden costs of each option.

Experienced team leads know how to evaluate each option's return on investment (ROI), which helps them make the best decision for the business.

That’s exactly how we ended up with Clerk. Their solution covers most of our use cases and from the business point of view, the ROI on implementing them to manage the users and organizations layer make sense.

Implementation

Novu service contains a lot of micro-services and aspects like:

Notification Channels (SMS, Email, In-app, Push, Chat etc..),
Notification Orchestration (Cross-Device Sync, Digest Engine, Delay, Timezone Awareness etc..)
Notification Observability (Debugging, Insights etc.)
Notification Content Management (Editor, Branding, Layouts, Translations, Variable Management etc..)
End-user management (User Preferences, Subscribers, Topics, Segments, Subscription Management etc..)
Account Management (SSO, Role Based Access Control, Multi-Tenancy, Billing etc..)

The diagram below shows a simplified version of Novu’s API structure, focusing only on the authentication and authorization of Novu users and organizations before implementing Clerk.

We use MongoDB to store all the data Novu requires, every user, organization, tenant, subscriber, topic… in short, everything.

Because Clerk have it’s own database to manage users, we needed to handle the migration and sync between the databases very carefully and precisely.

JWT strategy vs. Clerk strategy

One of the main things we needed to ensure is that UserSessionData object will not change to not break the session of the user when using Novu. It should remain compatible.

Here you can see the jwt.stratgy.ts file example:

//jwt.stratgy.ts
import type http from 'http';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { ApiAuthSchemeEnum, HttpRequestHeaderKeysEnum, UserSessionData } from '@novu/shared';
import { AuthService, Instrument } from '@novu/application-generic';
import { EnvironmentRepository } from '@novu/dal';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private readonly authService: AuthService, private environmentRepository: EnvironmentRepository) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: process.env.JWT_SECRET,
      passReqToCallback: true,
    });
  }
  @Instrument()
  async validate(req: http.IncomingMessage, session: UserSessionData) {
    // Set the scheme to Bearer, meaning the user is authenticated via a JWT coming from Dashboard
    session.scheme = ApiAuthSchemeEnum.BEARER;

    const user = await this.authService.validateUser(session);
    if (!user) {
      throw new UnauthorizedException();
    }

    await this.resolveEnvironmentId(req, session);

    return session;
  }

  @Instrument()
  async resolveEnvironmentId(req: http.IncomingMessage, session: UserSessionData) {
    // Fetch the environmentId from the request header
    const environmentIdFromHeader =
      (req.headers[HttpRequestHeaderKeysEnum.NOVU_ENVIRONMENT_ID.toLowerCase()] as string) || '';

    /*
     * Ensure backwards compatibility with existing JWTs that contain environmentId
     * or cached SPA versions of Dashboard as there is no guarantee all current users
     * will have environmentId in localStorage instantly after the deployment.
     */
    const environmentIdFromLegacyAuthToken = session.environmentId;

    let currentEnvironmentId = '';

    if (environmentIdFromLegacyAuthToken) {
      currentEnvironmentId = environmentIdFromLegacyAuthToken;
    } else {
      const environments = await this.environmentRepository.findOrganizationEnvironments(session.organizationId);
      const environmentIds = environments.map((env) => env._id);
      const developmentEnvironmentId = environments.find((env) => env.name === 'Development')?._id || '';

      currentEnvironmentId = developmentEnvironmentId;

      if (environmentIds.includes(environmentIdFromHeader)) {
        currentEnvironmentId = environmentIdFromHeader;
      }
    }

    session.environmentId = currentEnvironmentId;
  }
}

To maintain compatibility with the rest of the app, we needed to transformed the JWT payload from Clerk to the previously existing JWT format.

This is how we have done it:

async validate(payload: ClerkJwtPayload): Promise<IJwtClaims> {
  const jwtClaims: IJwtClaims = {
    // first time its clerk_id, after sync its novu internal id
    _id: payload.externalId || payload._id,
    firstName: payload.firstName,
    lastName: payload.lastName,
    email: payload.email,
    profilePicture: payload.profilePicture,
    // first time its clerk id, after sync its novu internal id
    organizationId: payload.externalOrgId || payload.org_id,
    environmentId: payload.environmentId,
    roles: payload.org_role ? [payload.org_role.replace('org:', '')] : [],
    exp: payload.exp,
  };

  return jwtClaims;
}

Here you can see the clerk.strategy.ts file example:

import type http from 'http';
import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { passportJwtSecret } from 'jwks-rsa';
import {
  ApiAuthSchemeEnum,
  ClerkJwtPayload,
  HttpRequestHeaderKeysEnum,
  PassportStrategyEnum,
  UserSessionData,
} from '@novu/shared';
import { EnvironmentRepository, EnvironmentEntity } from '@novu/dal';
import { LinkEntitiesService } from '../services/link-entities.service';

@Injectable()
export class ClerkStrategy extends PassportStrategy(Strategy, PassportStrategyEnum.JWT_CLERK) {
  constructor(private environmentRepository: EnvironmentRepository, private linkEntitiesService: LinkEntitiesService) {
    super({
      // ...configuration details
    });
  }

  async validate(req: http.IncomingMessage, payload: ClerkJwtPayload) {
    const { internalUserId, internalOrgId } = await this.linkEntitiesService.linkInternalExternalEntities(req, payload);

    const session: UserSessionData = {
      _id: internalUserId,
      firstName: payload.firstName,
      lastName: payload.lastName,
      email: payload.email,
      profilePicture: payload.profilePicture,
      organizationId: internalOrgId,
      roles: payload.org_role ? [payload.org_role.replace('org:', '')] : [],
      exp: payload.exp,
      iss: payload.iss,
      scheme: ApiAuthSchemeEnum.BEARER,
      environmentId: undefined,
    };

    await this.resolveEnvironmentId(req, session);

    return session;
  }

  // Other functions...
}

Sync between Clerk and Novu

While the goal is to use ideally only Clerk for creating and retrieving users, organization etc, unfortunately its not fully possible due to the need to store and query some metadata about users and organizations in a performant manner.

Here is an example of a method in Novu’s organization repository:

  async findPartnerConfigurationDetails(organizationId: string, userId: string, configurationId: string) {
    const organizationIds = await this.getUsersMembersOrganizationIds(userId);

    return await this.find(
      {
        _id: { $in: organizationIds },
        'partnerConfigurations.configurationId': configurationId,
      },
      { 'partnerConfigurations.$': 1 }
    );
  }

This method uses various MongoDB specific constructs to filter a document - this is not possible to reproduce using Clerk in a performant manner since thats not a database meant for such queries.

What we can do is to store these metadata about organization in our MongoDB organizations collection and link/sync the collection with the Clerk database using externalId.

Now we can combine both Clerk and MongoDB to query the metadata if needed.

async findPartnerConfigurationDetails(
  organizationId: string,
  userId: string,
  configurationId: string
): Promise<OrganizationEntity[]> {
  const clerkOrganizations = await this.getUsersMembersOrganizations(userId);

  return await this.communityOrganizationRepository.find(
    {
      _id: { $in: clerkOrganizations.map((org) => org.id) },
      'partnerConfigurations.configurationId': configurationId,
    },
    { 'partnerConfigurations.$': 1 }
  );
}

private async getUsersMembersOrganizations(userId: string): Promise<Organization[]> {
  const userOrgMemberships = await this.clerkClient.users.getOrganizationMembershipList({
    userId,
  });

  return userOrgMemberships.data.map((membership) => membership.organization);
}

By calling getUsersMembersOrganizations, findPartnerConfigurationDetails gets the necessary organization data to perform a filtered search on the communityOrganizationRepository, ensuring only relevant configurations are returned.

We need to sync only Users and Organizations between Clerk and Novu, the organization members doesn’t need to be synced.

Syncing users and organizations

There are two ways of how the database ids are synced:

middleware - any endpoint in API will sync the IDs if it detects that JWT doesn’t yet contain an internal ID.
webhook - as soon as the user/org is registered in Clerk, Clerk calls Novu’s API webhook, and we sync it.

Here is the flow we had in mind:

A user creates a new account via frontend using the Clerk component
Gets a new JWT containing Clerk user-id
Any request that hits the API triggers the syncing process (given it hasn’t yet happened)
A new user is created in Novu’s MongoDB containing the Clerk’s externalId
Clerk user object gets updated with Novu internal object id (saved as externalId in Clerk)
The new token returned from Clerk now contains an externalId that is equal to Novu's internal user ID.
In the Clerk strategy in validate() function on API - we set _id to equal to externalId so it is compatible with the rest of the app.

Note
In the application, we always expect Novu’s internal id on input and we always return internal id on output - its important for the application to work as is without major changes to the rest of the code.
API expects internal _id everywhere and it needs to be MongoDB ObjectID type, because it parses this user id back to ObjectID e.g. when creating new environment or any other entity which needs reference to user.

The same logic applies to organizations; just the endpoint is different.

What is stored in Clerk vs Novu

Users

For the users, we store everything in Clerk. All the properties are mostly just simple key/value pairs and we don’t need any advanced filtering on them, therefore they can be retrieved and updated directly in Clerk.

In internal MongoDB, we store just the user internal and external ids.

The original Novu user properties are stored in Clerk’s publicMetadata :

export type UserPublicMetadata = {
  profilePicture?: string | null;
  showOnBoardingTour?: number;
};

There are also many other attributes coming from Clerk which can be set on the user.

Organizations

For the organizations, we store everything in Clerk except for apiServiceLevel, partnerConfigurations, and branding since they are “native” to Clerk and we update those attributes directly there via frontend components and so we don’t need to sync with our internal DB after we change organization name or logo via Clerk component.

Injection of Enterprise Edition providers

The goal here was to replace the community (open source) implementation with Clerk while being minimally invasive to the application and to keep the Clerk implementation in a separate package.

This means we need to keep the changed providers (OrganizationRepository, AuthService…) on the same place with the same name so we don’t break the imports all over the place, but we need to change their body to be different based on feature flag.

The other option would be to change all of these providers in the 100+ of files and then import the EE(enterprise edition) package everywhere, which is probably not a good idea.

This turned out to be quite challenging due to the fact that users, organization and members are relatively deeply integrated to the application itself, referenced in a lot of places and they’re also tied to MongoDB specifics such as ObjectID or queries (create, update, findOne …).

The idea is to provide different implementation using NestJS dynamic custom providers where we are able to inject different class/service on compile time based on the enterprise feature flag.

This is the most promising solution we found while keeping the rest of the app mostly untouched, there are some drawbacks explained later.

AuthService & AuthModule - dynamic injection

We have two implementations of AuthService - community and enterprise one (in private package), we inject one of those as AUTH_SERVICE provider.

We need to however have a common interface for both IAuthService

Since we also need to change the AuthModule, we initialize two different modules based on the feature flag like this:

function getModuleConfig(): ModuleMetadata {
  if (process.env.NOVU_ENTERPRISE === 'true') {
    return getEEModuleConfig();
  } else {
    return getCommunityAuthModuleConfig();
  }
}

@Global()
@Module(getModuleConfig())
export class AuthModule {
  public configure(consumer: MiddlewareConsumer) {
    if (process.env.NOVU_ENTERPRISE !== 'true') {
      configure(consumer);
    }
  }
}

The reason why the EEModule can be a standalone module in the @novu/ee-auth package which we would just import instead of the original AuthModule and instead we are initializing one module conditionally inside API, is that we are reusing some original providers in the EE one - e.g. ApiKeyStrategy , RolesGuard, EnvironmentGuard etc which resides directly in API.

We would need to import them in the @novu/ee-auth package which would require to export these things somewhere (probably in some shared package) and it introduces other issues like circular deps etc - it can be however refactored later.

Repositories - users, organizations, members

Same logic applies for the repositories. No module is being initialized here, they’re just directly injected to the original repository classes.

Controllers

The controllers are being conditionally imported from inside @novu/api . The reason for that is the same as in the auth module, there are too many imports that the controllers uses, that we would either need to move to @novu/ee-auth or move them to a separate shared package - which would then trigger a much bigger change to the other unrelated parts of the app, which would increase the scope of this change.

function getControllers() {
  if (process.env.NOVU_ENTERPRISE === 'true') {
    return [EEOrganizationController];
  }

  return [OrganizationController];
}

@Module({
  controllers: [...getControllers()],
})
export class OrganizationModule implements NestModule {
    ...
}

Issues with this approach

The main issue here is the need for common interface for both of the classes - community and enterprise. You want to remain compatible in both community and enterprise versions, so when there is a this.organizationService.getOrganizations() method being called in 50 places in the app - you need an enterprise equivalent with the same name otherwise you need to change 50 places to call something else.

This results in not-so-strict typing and methods without implementation

We need to have a common interface for both, however the community one relies on MongoDB methods and needs different method arguments as the enterprise one which causes a use of any to forcefully fit both classes etc.
In some cases we don’t need the method at all, so we need to throw Not Implemented .

Endpoints modification

We modified the endpoints as follows:

AuthController: Removed and replaced by frontend calls to Clerk.
UserController: Removed, added a sync endpoint for Clerk users with MongoDB.
OrganizationController: Removed several endpoints, which can be migrated later.
InvitesController: Completely removed.
StorageModule: Completely removed.

Key points to consider and avoid

Avoid Storing Frequently Changing Properties in JWT
- Example: environmentID
- It can be cumbersome to update these properties.
Simplify Stored Data Structures
- Avoid storing complex structures in user, organization, or member records.
- Clerk performs optimally with simple key:value pairs, not arrays of objects.
Implement a User/Organization Replication Mechanism
- This helps bridge the gap during the migration period before Clerk is fully enabled.
- Use MongoDB triggers to replicate newly created users and organizations to both Clerk and your internal database.
Store Original Emails
- Do not sanitize emails as Clerk uses the original email as a unique identifier.

Team Spotlight

Lead Engineer: Adam Chmara

Platform Team Lead: Denis Kralj

Summary

Our implementation approach comes to the fact that we offloaded the Users, Organizations and Members management to Clerk.

The data property injection to Novu’s Controllers (endpoints) layer, Business layer and data layer happens based on “Enterprise” feature flag validation.

We are leveraging pre-built Clerk components on the frontend and reducing the need to build and maintain our own custom implementation on the backend.

You can also observe below the diagram of the current state after implementing Clerk.

Hindsight Bonus Points

When we made a decision to implement Clerk for user management, we also opt-in for the long-term benefits of expending the capabilities and features Clerk will support and offer in the future.

Here are some examples of what we might consider supporting in the near future:

Fine-grained access control (FGAC)
- Attribute-based: FGAC is often implemented using Attribute-Based Access Control (ABAC), where access decisions are based on various attributes of users, resources, and the environment. Attributes can include user role, department, resource type, time of day, and more.
- Flexibility: FGAC offers greater flexibility and granularity by allowing detailed, condition-based access controls. This means permissions can be fine-tuned to very specific scenarios.
- Dynamic: FGAC can adapt dynamically to changes in the environment, such as time-sensitive access or location-based restrictions.
- Detailed permissions: Permissions in FGAC are more specific and can be tailored to individual actions, users, or situations.

Provide this level of detailed flexibility to Novu, might have been out of the scope or even scraped at the gate because of the potential complexity of implementation.

User impersonation

Our costumer success or support teams could use this to troubleshoot issues, provide support, or test functionality from the perspective of the impersonated user without needing to know their password or other authentication details.
- Reduces the time and complexity involved in diagnosing and resolving user issues.
- Ensures that the support or administrative actions taken are accurate since the support staff can see and interact with the system exactly as the user would.
- Enhances user satisfaction by providing faster and more effective support.

Simply put, we will be able to improve the experience for Novu users with ease given that the fact that now, the authentication infrastructure is lied out for it.

If you would like to suggest additional features involving AuthN (or any other), visit our Roadmap to review and upvote requests, or submit your idea.

How Product-Development Friction Ruins User Experience with Notifications

Kevin Damaso — Sat, 27 Jul 2024 00:47:07 +0000

User engagement is as much art as it is science. Since Product and Engineering teams are busy focusing their time and energy on building the core application that delights users and powers their business, notifications are often treated as an afterthought.

Usually, the conversation goes something like "Send users an order confirmation email," or "send an OTP text when they log in." The team then creates a confirmation email and OTP text because it’s easy and takes no time. Fast forward 6 months and new requests for different notification types, channels, and features come in. This results in building these notifications in disconnected ways, possibly having to refactor the entire system with each new addition.

As we can see above, engineering effort is minimal to create a basic notification. However, once implemented, it is very challenging to scale as end-users demand a more robust and customized notifications experience.

The challenge that arises from this is that even inside the seemingly simplest of app activities, a poor notifications experience is lurking, ready to hurt your carefully crafted user experience, or worse, damage your brand in the process.

Say no to clunky notifications

As a product manager looking to provide clients with an excellent user experience, one of the biggest challenges you face is having clunky a notifications system.

A clunky user experience is symptomatic of the following core issues:

Lack of user control over which notifications they get, and when, where, and why they get them.
Lack of brand consistency.
Developers or an external source are required to make changes to notifications.
Unique content, systems, and sources for each notification app, function, or channel.
Lack of visibility and awareness if a message has or has not been delivered, and the time-consuming troubleshooting when things go wrong.

Core notification challenges details

Lack of user preferences

Allow users to set their individual preferences

The bar for user experience has been raised, and setting individual preferences is now table stakes. It’s simply a part of the common notification experience that your users expect. How do you ensure that user preferences are being met?

”We want to have a tool that is capable of managing the preference and the user info, to allow the customer to constantly update if he wants to receive email, SMS, through the mobile app, and so on.”

— Lead Platform Product Manager, automotive software

Some of your users might not want to receive emails. In that case, how does the system know to send SMS, or WhatsApp instead? If these notification types are set by the business, but stored in different systems, it's much harder for a product manager to ensure no user is left behind.

Importantly, this also helps prevent sending a barrage of notifications all at once.

A centralized notification platform helps you deliver notifications to your users where they want it, when they want it, how they want it.

Lack of brand consistency

Create a consistent user-experience through standardized templates and branding controls

Oftentimes, especially when relying on engineering teams or professional services to make changes, there’s a lack of brand consistency.

Stop me if this sounds familiar when describing your notifications:

The word I would use is clunky. There is not a lot of consistency and there are a lot of holes in exactly what things look like.”

— VP Product Manager, banking

Without a template management system upon which to standardize your notifications, this is too often the result.
A typical workflow is that product will deliver a PDF or a Figma design to the engineering team or external service provider, who then have to code the design to spec. Along the way, something of the notification gets lost in translation.

Reliant on engineering to make changes

Enable product teams to iterate on notifications without requiring engineering through the dashboard UI

“It requires engineering effort to make changes. We have a number of product and operations teams, who would like to have influence over messaging, verbiage, and cadence. We want to run experiments, and our current solution isn't able to support that...”

— Lead Product Manager, e-commerce software

This lack of ability to manage notifications directly makes it a black box. For non-technical team members, this leaves them without control over their own destiny. Not only does it hamper experimentation, and thus innovation, it also decreases velocity by adding multiple feedback and review cycles to work that the product or operations team need to own.

We often speak with organizations that are using some type of enterprise solution that has a “notifications module” to manage their application notifications. This experience typically comes with a lot of back and forth with the external professional services team and lacks true ownership of content and overall message.

In the same way that DevSecOps aims to shift-left, moving security and vulnerability to the hands of the developers who have the most context and can remediate immediately, we should aim to shift notifications left, into the hands of the product teams that have the most context over the messages they’re sending.

Product teams shouldn’t have to rely on development teams to fix a typo, tweak wording, or update a logo or other image.

Lack of centralization

Novu centralizes notifications and allows engineers to easily leverage existing providers through our integrations

Teams should not have to work in multiple multiple notification systems, depending on the type of message, the channel it’s being sent through, or the function it’s being sent for.

“You can imagine what happens when every department builds their own notification system within their own use cases and their own functions. That gets to be a real challenge when I'm a product manager and I just want to send a notification out. I would like to go to one place as opposed to all these other individual systems.”

—Director of Product Management, automotive manufacturer

Disparate systems further exacerbates a lack of consistency. It manifests in subtle ways, such as look-and-feel, elements within the in-application notifications being different from what’s sent in an email, inconsistent wording, and mixed messaging.

But it also adds cognitive overhead. As a product-led software organization, you may have multiple feature teams which develop notifications independently. For example, you likely have a mobile team that cares about push notifications, a separate team that cares about text messages, a payments team that implements email invoices, and so on and so forth. Those are several teams that need to then be coordinated for execution.

This is why notification management should be centralized.

Troubleshooting message delivery

The fifth aspect of user experience is message delivery.

“Is there a way we can actually follow a single message, see if it's delivered for a specific device or specific user, so we can test it, make sure that particular message has been sent and received?”

— Managing Director, accounting software

Disparate systems make observability exponentially more difficult.

Having a single platform makes it easier to troubleshoot and debug when notifications fail, and furthermore, have built-in retries to ensure delivery.

Engineering and development teams want this too

The good news is that product managers aren’t alone in facing these challenges. Development teams want to solve notifications too.

“Instead of hand-rolling the rules, sending an email, change custom icons in the app. I want to get out of all that customization, streamline the delivery for my product team, and make the customer experience better.”

—CTO, communication software

The common denominator across a clunky user experience is the lack of a centralized notifications platform, where engineering and product teams can collaborate.

This allows development teams to:

create templates for brand consistency
empower product teams to directly manage messaging and cadence
offload notifications logic, user preferences, and more
quickly debug and troubleshoot notifications issues

The Novu way

To recap, product managers want to deliver an excellent user experience through notifications. However, they are often faced with a lack of ownership over the notifications they send, leading to messaging, design, and branding inconsistency, and an inability to experiment with verbiage, cadence, or really anything else.

The solution is to empower both product and development teams to collaborate, where each team team controls the parts they care about: logic, integrations, and data sources for development teams, and cadence, messaging, experience, and functionality for product teams.

A powerful, centralized notifications framework enables development and engineering teams to easily build a scalable, reliable, and infinitely flexible notifications platform to product teams.

In parallel, product teams directly interact with the notification types, content, messaging, styles, branding, etc… they completely control all components of a notification they want to—all without the risk of breaking sensitive business and software logic.

End users benefits from all of this. Rich, interactive notifications in the channels they prefer. Flexible, accessible preferences means they, too, are in control of how you communicate with them.

If you, like our customers, are under tight timelines and looking to deploy features more quickly, it makes sense to try Novu. Instead of looking to build this in house, maintain it, and expand (cough* refactor* cough) as new features are required, avoid the unknowns and use the standard for notifications infrastructure.

Building An E-Commerce Store With NextJS

Emil Pearce — Tue, 04 Jun 2024 18:52:25 +0000

In this tutorial, you'll learn how to build an e-commerce store where customers can purchase products and make payments via Stripe. After a successful payment, an email notification is sent to the customer, and an in-app notification to the Admin user. The Admin user can also create and delete products within the application.

To build this application, we'll use the following tools:

Appwrite - for authenticating users, as well as saving and retrieving product details.
Next.js - for creating the application’s user interface and backend.
Novu - for sending email and in-app notifications.
React Email - for creating email templates.
Stripe - for integrating a payment checkout to the application.

Building the application interface with Next.js

The application pages are divided into two parts based on the roles assigned to the users. Customers can access the Home page and sign in to the application before making payments. Admin users can access all pages, including a sign-in page and a dashboard page where they can add and remove products.

Now, let's build the application.

Create a new Next.js Typescript project by running the code snippet below:

npx create-next-app novu-store

Next, install React Icons and the Headless UI package. React Icons allows us to use various icons within the application, while Headless UI provides easy-to-use modern UI components.

npm install react-icons @headlessui/react

Copy this code snippet from the GitHub repository into the app/page.tsx file. It renders a list of products on the screen and allows users to select items in a cart, similar to the image below.

Create a login route that enables users to sign using their GitHub account. Copy the code snippet below into the app/login/page.tsx file.

//👉🏻 create a login folder containing a page.tsx file
export default function Home() {
    const handleGoogleSignIn = async () => {};

    return (
        <main className='w-full min-h-screen flex flex-col items-center justify-center'>
            <h2 className='font-semibold text-3xl mb-2'>Customer Sign in</h2>
            <p className='mb-4 text-sm text-red-500'>
                You need to sign in before you can make a purchase
            </p>
            <button
                className='p-4 border-[2px] border-gray-500 rounded-md hover:bg-black hover:text-white w-2/3'
                onClick={() => handleGoogleSignIn()}
            >
                Sign in with GitHub
            </button>
        </main>
    );
}

When users click the Sign in button, it redirects them to the GitHub authentication page and prompts them to sign in to the application. You'll learn how to do this with Appwrite shortly.

Next, let's create the admin pages. Add an admin folder containing a login and dashboard route within the app folder.

cd app
mkdir admin && cd admin
mkdir dashboard login

Add a page.tsx file within the dashboard and login folders, and copy the code snippet below into the login/page.tsx file.

"use client";
import Link from "next/link";
import { useState } from "react";

export default function Login() {
    const [email, setEmail] = useState<string>("");
    const [password, setPassword] = useState<string>("");

    const handleLogin = async (e: React.FormEvent) => {
        e.preventDefault();
        console.log({ email, password });
    };

    return (
        <main className='w-full min-h-screen flex flex-col items-center justify-center'>
            <h2 className='font-semibold text-3xl mb-4'> Admin Sign in</h2>
            <form className='w-2/3' onSubmit={handleLogin}>
                <label htmlFor='email' className='block'>
                    Email
                </label>
                <input
                    type='email'
                    id='email'
                    className='w-full px-4 py-3 border border-gray-400 rounded-sm mb-4'
                    required
                    value={email}
                    placeholder='admin@admin.com'
                    onChange={(e) => setEmail(e.target.value)}
                />

                <label htmlFor='password' className='block'>
                    Password
                </label>
                <input
                    type='password'
                    id='password'
                    className='w-full px-4 py-3 border border-gray-400 rounded-sm mb-4'
                    required
                    value={password}
                    placeholder='admin123'
                    onChange={(e) => setPassword(e.target.value)}
                />
                <button className='p-4 text-lg mb-3 bg-blue-600 text-white w-full rounded-md'>
                    Sign in
                </button>
                <p className='text-sm text-center'>
                    Not an Admin?{" "}
                    <Link href='/login' className='text-blue-500'>
                        Sign in as a Customer
                    </Link>
                </p>
            </form>
        </main>
    );
}

The code snippet above renders a form that accepts the Admin's email and password, validates the credentials, and then logs the user into the application.

The Admin dashboard page renders the available products and allows the Admin user to add and delete products from the application. Copy this code snippet into the dashboard/page.tsx file to create the user interface.

Congratulations! You've built the application interface. In the upcoming sections, you'll learn how to connect the application to an Appwrite backend and send data between the client and the server.

How to add Appwrite to a Next.js application

Appwrite is an open-source backend service that enables you to create secure and scalable software applications. It offers features such as multiple authentication methods, a secure database, file storage, cloud messaging, and more, which are essential for building full-stack applications.

In this section, you'll learn how to set up an Appwrite project, including features such as authentication, database, and file storage.

First, visit Appwrite Cloud, and create an account and organization for your projects.

Next, create a new project and select your preferred region for hosting the project.

Select Web as the platform SDK for the application.

Follow the steps displayed on the screen. Since you're currently building in development mode, you can use the wildcard (*) as your hostname and change it to your domain name after deploying the application.

Install the Appwrite client SDK within your Next.js project.

npm install appwrite

Finally, create an appwrite.ts file within your Next.js app folder and copy the code snippet below into the file to initialize Appwrite.

import { Client, Account, Databases, Storage } from "appwrite";

const client = new Client();

client
    .setEndpoint("https://cloud.appwrite.io/v1")
    .setProject(<YOUR_PROJECT_ID>);

export const account = new Account(client);

export const db = new Databases(client);

export const storage = new Storage(client);

Setting up GitHub Authentication with Appwrite

Here, you'll learn how to set up GitHub and Email/Password authentication with Appwrite. Email/Password authentication is already configured by default, so let's focus on setting up GitHub authentication.

Before we proceed, you need to create a GitHub OAuth application using your GitHub account. Appwrite will require the client ID and secrets to set up GitHub authentication.

Enable Appwrite's GitHub authentication method by selecting Auth from the sidebar menu and navigating to the Settings tab.

Copy your GitHub client ID and secret into the Appwrite's GitHub OAuth settings.

Finally, ensure you copy the URI generated by Appwrite into your GitHub app settings.

Setting up Appwrite Database

Select Databases from the sidebar menu and create a new database. You can name it novu store.

Next, create a products collection. It will contain the lists of products within the application.

Add name, price, and image attributes to the collection.

Under the Settings tab, update the permissions to allow every user to perform CRUD operations. However, you can change this after deploying the application to ensure that only authenticated users can perform various actions.

Finally, copy your project, database, and collection IDs into an .env.local file. This keeps your credentials safe and allows you to reference each value from its environment variables.

NEXT_PUBLIC_PROJECT_ID=<YOUR_PROJECT_ID>
NEXT_PUBLIC_DB_ID=<YOUR_DATABASE_ID>
NEXT_PUBLIC_PRODUCTS_COLLECTION_ID=<YOUR_DB_COLLECTION_ID>

Setting up Appwrite Storage

Select Storage from the sidebar menu and create a new bucket that will hold all the product images.

Under the Settings tab, update the Permissions to allow any user for now.

Set the acceptable file formats. Since we are uploading images, you can select the .jpg and .png file formats.

Finally, copy your bucket ID into .env.local file.

NEXT_PUBLIC_BUCKET_ID=<YOUR_BUCKET_ID>

Congratulations! You've successfully configured Appwrite. We can now start interacting with its various features.

How to perform CRUD operations with Appwrite

In this section, you'll learn how to create, retrieve, and delete products from Appwrite. Users need to be able to view existing products before making a purchase, while Admin users should have the permission to add and delete products from the application.

First, create a utils.ts file within the Next.js app folder. This file will contain all Appwrite database interactions, which you can then import into the necessary pages.

cd app
touch utils.ts

Saving products to Appwrite

Recall that the products collection has three attributes: name, image, and price. Therefore, when adding products to the database, you need to first upload the product's image, retrieve its URL and ID from the response, and then upload the URL as the product's image attribute, using the image's storage ID for the product data.

Here is the code snippet that explains this:

import { db, storage } from "@/app/appwrite";
import { ID } from "appwrite";

export const createProduct = async (
    productTitle: string,
    productPrice: number,
    productImage: any
) => {
    try {
        //👇🏻 upload the image
        const response = await storage.createFile(
            process.env.NEXT_PUBLIC_BUCKET_ID!,
            ID.unique(),
            productImage
        );
        //👇🏻 get the image's URL
        const file_url = `https://cloud.appwrite.io/v1/storage/buckets/${process.env.NEXT_PUBLIC_BUCKET_ID}/files/${response.$id}/view?project=${process.env.NEXT_PUBLIC_PROJECT_ID}&mode=admin`;

        //👇🏻 add the product to the database
        await db.createDocument(
            process.env.NEXT_PUBLIC_DB_ID!,
            process.env.NEXT_PUBLIC_PRODUCTS_COLLECTION_ID!,
            response.$id, //👉🏻 use the image's ID
            {
                name: productTitle,
                price: productPrice,
                image: file_url,
            }
        );
        alert("Product created successfully");
    } catch (err) {
        console.error(err);
    }
};

The code snippet above uploads the image to Appwrite's cloud storage and retrieves the exact image URL using the bucket ID, image ID, and project ID. Once the image is successfully uploaded, its ID is used in the product's data to enable easy retrieval and reference.

Retrieving products from Appwrite

To fetch the products from Appwrite, you can execute the function below within the React useEffect hook when the page loads.

export const fetchProducts = async () => {
    try {
        const products = await db.listDocuments(
            process.env.NEXT_PUBLIC_DB_ID!,
            process.env.NEXT_PUBLIC_PRODUCTS_COLLECTION_ID!
        );
        if (products.documents) {
            return products.documents;
        }
    } catch (err) {
        console.error(err);
    }
};

The fetchProducts function returns all the data within the products collection.

Deleting products from Appwrite

Admin users can also delete a product via its ID. The deleteProduct function accepts the product's ID as a parameter and deletes the selected product from the database, including its image, since they use the same ID attribute.

export const deleteProduct = async (id: string) => {
    try {
        await db.deleteDocument(
            process.env.NEXT_PUBLIC_DB_ID!,
            process.env.NEXT_PUBLIC_PRODUCTS_COLLECTION_ID!,
            id
        );
        await storage.deleteFile(process.env.NEXT_PUBLIC_BUCKET_ID!, id);

        alert("Product deleted successfully");
    } catch (err) {
        console.error(err);
    }
};

How to authenticate users with Appwrite

In the previous sections, we've configured the GitHub authentication method. Here, you'll learn how to handle user sign-ins into the application.

To enable customers to sign into the application using their GitHub account, execute the function below when they click the Sign in button. The function redirects the user to GitHub, where they can authorize or grant permission to the application and then sign into the application:


import { account } from "../appwrite";
import { OAuthProvider } from "appwrite";

const handleGoogleSignIn = async () => {
    try {
        account.createOAuth2Session(
            OAuthProvider.Github,
            "http://localhost:3000",
            "http://localhost:3000/login"
        );
    } catch (err) {
        console.error(err);
    }
};

Admin users can sign into the application using an email and password. Appwrite validates the credentials before granting access to the application's dashboard.

import { account } from "@/app/appwrite";

const handleLogin = async (e: React.FormEvent) => {
    e.preventDefault();
    try {
        await account.createEmailPasswordSession(email, password);
        alert(`Welcome back 🎉`);
        router.push("/admin/dashboard");
    } catch (err) {
        console.error(err);
        alert("Invalid credentials ❌");
    }
};

Appwrite also allows you to fetch the current user's data. For instance, if only authenticated users can make payments, you can do this by running the code snippet below. It retrieves the current user's data or returns null if the user is not logged in.

import { account } from "@/app/appwrite";

useEffect(() => {
    const checkAuthStatus = async () => {
        try {
            const request = await account.get();
            setUser(request);
        } catch (err) {
            console.log(err);
        }
    };
    checkAuthStatus();
}, []);

How to add Stripe payment checkout to Next.js

In this section, you'll learn how to implement a Stripe payment checkout in the application. Stripe is a popular online payment processing platform that enables you to create products and integrate both one-time and recurring payment methods into your application.

First, you need to create a Stripe account. You can use a test mode account for this tutorial.

Click on Developers from the top menu and copy your secret key from the API keys menu.

Paste your Stripe secret key into the .env.local file.

STRIPE_SECRET_KEY=<your_secret_key>

Install the Stripe Node.js SDK.

npm install stripe

Next, create an api folder within the Next.js app folder. The api folder will contain all the API routes and endpoints for the application.

cd app
mkdir api

Create a checkout endpoint by adding a checkout folder within the api folder.

cd api
mkdir checkout && cd checkout
touch route.ts

Copy the code snippet below into the route.ts file.

import { NextRequest, NextResponse } from "next/server";
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: NextRequest) {
    //👇🏻 accepts the customer's cart
    const cart = await req.json();

    try {
        //👇🏻 creates a checkout session
        const session = await stripe.checkout.sessions.create({
            payment_method_types: ["card"],
            line_items: cart.map((product: Product) => ({
                price_data: {
                    currency: "usd",
                    product_data: {
                        name: product.name,
                    },
                    unit_amount: product.price * 100,
                },
                quantity: 1,
            })),
            mode: "payment",
            cancel_url: `http://localhost:3000/?canceled=true`,
            success_url: `http://localhost:3000?success=true&session_id={CHECKOUT_SESSION_ID}`,
        });
        //👇🏻 return the session URL
        return NextResponse.json({ session: session.url }, { status: 200 });
    } catch (err) {
        return NextResponse.json({ err }, { status: 500 });
    }
}

The code snippet above creates a checkout endpoint that accepts POST requests. It creates a checkout session for the customer and returns the session URL.

The cancel_url and success_url determine where to redirect the user after completing or canceling a payment.

Finally, you can send a customer's cart to the /checkout endpoint when a user decides to make payment for products by running the code snippet below:

const processPayment = async (cart: Product[]) => {
    try {
        if (user !== null) {
            //👇🏻 saves cart to local storage
            localStorage.setItem("cart", JSON.stringify(cart));
            //👇🏻 sends cart to /checkout route
            const request = await fetch("/api/checkout", {
                method: "POST",
                body: JSON.stringify(cart),
                headers: { "Content-Type": "application/json" },
            });
            //👇🏻 retrieves the session URL
            const { session } = await request.json();
            //👇🏻 redirects the user to the checkout page
            window.location.assign(session);
        } else {
            //👇🏻 redirects unauthenticated users
            router.push("/login");
        }
    } catch (err) {
        console.error(err);
    }
};

The code snippet above saves the cart to the browser's local storage and sends it to the API endpoint, then retrieves the response (session URL) from the backend server and redirects the user to the Stripe checkout page.

Sending in-app and email notifications with Novu

Novu is the first notification infrastructure that provides a unified API for sending notifications through multiple channels, including In-App, Push, Email, SMS, and Chat.

In this section, you'll learn how to add Novu to your application to enable you to send email and in-app messages.

First, install the required Novu packages:

npm install @novu/node @novu/echo @novu/notification-center

When users make a purchase, they will receive a payment confirmation email, and the admin user also receives an in-app notification.

To do this, you need to create an account on Novu and set up a primary email provider. We'll use Resend for this tutorial.

After creating an account on Novu, create a Resend account, and select API Keys from the sidebar menu on your dashboard to create one.

Next, return to your Novu dashboard, select Integrations Store from the sidebar menu, and add Resend as an email provider. You'll need to paste your Resend API key and email address into the required fields.

Select Settings from the sidebar menu and copy your Novu APIkey and App ID into a .env.local file as shown below. Also, copy your subscriber ID into its field - you can get this from the Subscribers section.

NOVU_API_KEY=<YOUR_API_FOR_NEXT_SERVER>
NEXT_PUBLIC_NOVU_API_KEY=<YOUR_API_FOR_NEXT_CLIENT>

NEXT_PUBLIC_NOVU_APP_ID=<YOUR_API_ID>

NOVU_SUBSCRIBER_ID=<YOUR_API_FOR_NEXT_SERVER>
NEXT_PUBLIC_NOVU_SUBSCRIBER_ID=<YOUR_API_FOR_CLIENT>

Finally, add the Novu notification bell to the Admin dashboard to enable admin users to receive notifications within the application.

import {
    NovuProvider,
    PopoverNotificationCenter,
    NotificationBell,
} from "@novu/notification-center";

export default function AdminNav() {
    return (
        <NovuProvider
            subscriberId={process.env.NEXT_PUBLIC_NOVU_SUBSCRIBER_ID!}
            applicationIdentifier={process.env.NEXT_PUBLIC_NOVU_APP_ID!}
        >
            <PopoverNotificationCenter colorScheme='light'>
                {({ unseenCount }) => <NotificationBell unseenCount={unseenCount} />}
            </PopoverNotificationCenter>
        </NovuProvider>
    );
}

How to create notification workflows with Novu Echo

Novu offers a code-first workflow engine that enables you to create notification workflows within your codebase. It allows you to integrate email, SMS, and chat template and content generators, such as React Email and MJML, into Novu to create advanced and powerful notifications.

In this section, you'll learn how to create notification workflows within your application, use email notification templates with Novu, and send in-app and email notifications with Novu.

Install React Email by running the following command:

npm install react-email @react-email/components -E

Include the following script in your package.json file. The --dir flag gives React Email access to the email templates located within the project. In this case, the email templates are located in the src/emails folder.

{
    "scripts": {
        "email": "email dev --dir src/emails"
    }
}

Next, create an emails folder containing an email.tsx within the Next.js app folder and copy the code snippet below into the file:

import {
    Body,
    Column,
    Container,
    Head,
    Heading,
    Hr,
    Html,
    Link,
    Preview,
    Section,
    Text,
    Row,
    render,
} from "@react-email/components";
import * as React from "react";

const EmailTemplate = ({
    message,
    subject,
    name,
}: {
    message: string;
    subject: string;
    name: string;
}) => (
    <Html>
        <Head />
        <Preview>{subject}</Preview>
        <Body style={main}>
            <Container style={container}>
                <Section style={header}>
                    <Row>
                        <Column style={headerContent}>
                            <Heading style={headerContentTitle}>{subject}</Heading>
                        </Column>
                    </Row>
                </Section>

                <Section style={content}>
                    <Text style={paragraph}>Hey {name},</Text>
                    <Text style={paragraph}>{message}</Text>
                </Section>
            </Container>

            <Section style={footer}>
                <Text style={footerText}>
                    You&apos;re receiving this email because your subscribed to Newsletter
                    App
                </Text>

                <Hr style={footerDivider} />
                <Text style={footerAddress}>
                    <strong>Novu Store</strong>, &copy;{" "}
                    <Link href='https://novu.co'>Novu</Link>
                </Text>
            </Section>
        </Body>
    </Html>
);

export function renderEmail(inputs: {
    message: string;
    subject: string;
    name: string;
}) {
    return render(<EmailTemplate {...inputs} />);
}

const main = {
    backgroundColor: "#f3f3f5",
    fontFamily: "HelveticaNeue,Helvetica,Arial,sans-serif",
};

const headerContent = { padding: "20px 30px 15px" };

const headerContentTitle = {
    color: "#fff",
    fontSize: "27px",
    fontWeight: "bold",
    lineHeight: "27px",
};

const paragraph = {
    fontSize: "15px",
    lineHeight: "21px",
    color: "#3c3f44",
};

const divider = {
    margin: "30px 0",
};

const container = {
    width: "680px",
    maxWidth: "100%",
    margin: "0 auto",
    backgroundColor: "#ffffff",
};

const footer = {
    width: "680px",
    maxWidth: "100%",
    margin: "32px auto 0 auto",
    padding: "0 30px",
};

const content = {
    padding: "30px 30px 40px 30px",
};

const header = {
    borderRadius: "5px 5px 0 0",
    display: "flex",
    flexDireciont: "column",
    backgroundColor: "#2b2d6e",
};

const footerDivider = {
    ...divider,
    borderColor: "#d6d8db",
};

const footerText = {
    fontSize: "12px",
    lineHeight: "15px",
    color: "#9199a1",
    margin: "0",
};

const footerLink = {
    display: "inline-block",
    color: "#9199a1",
    textDecoration: "underline",
    fontSize: "12px",
    marginRight: "10px",
    marginBottom: "0",
    marginTop: "8px",
};

const footerAddress = {
    margin: "4px 0",
    fontSize: "12px",
    lineHeight: "15px",
    color: "#9199a1",
};

The code snippet above creates an customizable email template using React Email. You can find more easy-to-edit inspirations or templates. The component also accepts a message, subject, and name as props, and fills them into the elements.

Finally, you can run npm run email in your terminal to preview the template.

Next, let's integrate the email template to Novu Echo. First, close the React Email server, and run the code snippet below. It opens the Novu Dev Studio in your browser.

npx novu-labs@latest echo

Create an echo folder containing a client.ts file within the Next.js app folder and copy this code snippet into the file.

import { Echo } from "@novu/echo";
import { renderEmail } from "@/app/emails/email";

interface EchoProps {
    step: any;
    payload: {
        subject: string;
        message: string;
        name: string;
        totalAmount: string;
    };
}
export const echo = new Echo({
    apiKey: process.env.NEXT_PUBLIC_NOVU_API_KEY!,
    devModeBypassAuthentication: process.env.NODE_ENV === "development",
});

echo.workflow(
    "novu-store",
    async ({ step, payload }: EchoProps) => {
        //👇🏻 in-app notification step
        await step.inApp("notify-admin", async () => {
            return {
                body: `${payload.name} just made a new purchase of ${payload.totalAmount} 🎉`,
            };
        });
        //👇🏻 email notification step
        await step.email(
            "email-customer",
            async () => {
                return {
                    subject: `${payload ? payload?.subject : "No Subject"}`,
                    body: renderEmail(payload),
                };
            },
            {
                inputSchema: {
                    type: "object",
                    properties: {},
                },
            }
        );
    },
    {
        payloadSchema: {
            type: "object",
            properties: {
                message: {
                    type: "string",
                    default: "Congratulations! Your purchase was successful! 🎉",
                },
                subject: { type: "string", default: "Message from Novu Store" },
                name: { type: "string", default: "User" },
                totalAmount: { type: "string", default: "0" },
            },
            required: ["message", "subject", "name", "totalAmount"],
            additionalProperties: false,
        },
    }
);

The code snippet defines a Novu notification workflow named novu-store, which accepts a payload containing the email subject, message, the customer's name and the total amount.

The workflow has two steps: in-app and email notification. The in-app notification sends a message to the Admin using the notification bell and the email sends a message to the customer’s email.

Next, you need to create an API route for Novu Echo. Within the api folder, create an email folder containing a route.ts file and copy the provided code snippet below into the file.

import { serve } from "@novu/echo/next";
import { echo } from "@/app/echo/client";

export const { GET, POST, PUT } = serve({ client: echo });

Run npx novu-labs@latest echo in your terminal. It will automatically open the Novu Dev Studio where you can preview your workflow and Sync it with the Cloud.

The Sync to Cloud button triggers a pop-up that provides instructions on how to push your workflow to the Novu Cloud.

To proceed, run the following code snippet in your terminal. This will generate a unique URL representing a local tunnel between your development environment and the cloud environment.

npx localtunnel --port 3000

Copy the generated link along with your Echo API endpoint into the Echo Endpoint field, click the Create Diff button, and deploy the changes.

https://<LOCAL_TUNNEL_URL>/<ECHO_API_ENDPOINT (/api/email)>

Congratulations! You've just created a Novu workflow from your codebase.

Finally, let's create the endpoint that sends the email and in-app notifications when a user makes a payment. Create an api/send route and copy the code snippet below into the file:

import { NextRequest, NextResponse } from "next/server";
import { Novu } from "@novu/node";

const novu = new Novu(process.env.NOVU_API_KEY!);

export async function POST(req: NextRequest) {
    const { email, name, totalAmount } = await req.json();

    const { data } = await novu.trigger("novu-store", {
        to: {
            subscriberId: process.env.NOVU_SUBSCRIBER_ID!,
            email,
            firstName: name,
        },
        payload: {
            name,
            totalAmount,
            subject: `Purchase Notification from Novu Store`,
            message: `Your purchase of ${totalAmount} was successful! 🎉`,
        },
    });
    console.log(data.data);

    return NextResponse.json(
        {
            message: "Purchase Completed!",
            data: { novu: data.data },
            success: true,
        },
        { status: 200 }
    );
}

The endpoint accepts the customer's email, name, and total amount paid, and triggers the Novu notification workflow to send the required notifications after a payment is successful.

Conclusion

So far, you've learned how to do the following:

Implement multiple authentication methods, store, and retrieve data and files from Appwrite.
Create email templates with React Email, and send in-app and email notifications with Novu.

If you are looking forward to sending notifications within your applications, Novu is your best choice. With Novu, you can add multiple notification channels to your applications, including chat, SMS, email, push, and in-app notifications.

The source code for this tutorial is available here:
https://github.com/novuhq/ecom-store-with-nextjs-appwrite-novu-and-stripe

Thank you for reading!

How To Build Your Own Newsletter App? р.2

Emil Pearce — Thu, 16 May 2024 11:29:14 +0000

Sending newsletters with Novu and React Email

We’ll leverage Novu’s code-first workflow (Echo) approach in creating notification workflows within our codebase. Novu empowers you with the ability to integrate email, SMS, and chat template and content generators, such as React Email, and MJML into your app via code.

Within this section, you'll grasp the art of crafting notification workflows using Novu Echo, designing email templates with React Email, and seamlessly sending emails via Novu.

First, you need to create an account on Novu and set up a primary email provider. We'll use Resend for this tutorial.

After creating an account on Novu, create a Resend account, and select API Keys from the sidebar menu on your dashboard to create one.

Finally, select Settings from the sidebar menu and copy your Novu API key into a .env.local file as shown below.

# For Novu SDK
NOVU_API_KEY=<YOUR_NOVU_API_KEY>

# For Echo Client
NEXT_PUBLIC_NOVU_API_KEY=<YOUR_NOVU_API_KEY>

The API route for creating newsletters

Navigate to the components/Newsletters.tsx file, which contains the form that enables Admin users to send newsletters to subscribers. Copy the functions below into this file.

const [subscribers, setSubscribers] = useState<SubscribersData[]>([]);

//👇🏻 fetch the subscribers' emails from Firebase
const fetchSubscribers = async () => {
    try {
        const querySnapshot = await getDocs(collection(db, "subscribers"));
        const emails: string[] = [];
        const subs: any = [];
        querySnapshot.forEach((doc) => {
            const dt = doc.data();
            emails.push(dt.email);
            subs.push(dt);
        });
        setSubscribers(subs);
    } catch (e) {
        console.error("Error fetching subscribers", e);
    }
};

//👇🏻 gets the list of subscribers on page load
useEffect(() => {
    fetchSubscribers();
}, []);

//👇🏻 send form data to the backend API route
const emailNewsletter = async () => {
    try {
        const request = await fetch("/api/send", {
            method: "POST",
            body: JSON.stringify({ subject, message, subscribers }),
        });
        const response = await request.json();
        if (response.success) {
            console.log({ response });
        }
    } catch (err) {
        console.error(err);
    }
};

The provided code snippet retrieves the list of subscribers from Firebase and sends them, along with the email's message and subject, to the /api/send API route, where the emails are forwarded to the subscribers via Novu.

The fetchSubscribers function retrieves the subscribers from Firebase, while the emailNewsletter function sends a POST request containing the subscribers' data, email subject, and content to the api/send Next.js API route.

To proceed, let's set up the required API routes. Create an api/send folder within the Next.js app folder.

cd app
mkdir api && cd api
mkdir send

Create a route.ts file within the send folder that accepts the form data.

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
    const { subject, message, subscribers } = await req.json();

    return NextResponse.json(
        {
            message: "Data received!",
            data: {subject, message: subscribers}
            success: true,
        },
        { status: 200 }
    );
}

Now, we can use this data to send email templates using Novu Echo and React Email.

Code-first email notification workflow with Novu and React Email

Run this code snippet in your terminal to install the Novu SDK and Novu Echo to the Next.js project. We'll create the notification workflow with Novu Echo and pass a payload from the API server to the workflow, then into the React Email template.

npm install @novu/node @novu/echo

Next, install React Email by running the following command:

npm install react-email @react-email/components -E

Include the following script in your package.json file. The --dir flag gives React Email access to the email templates located within the project. In this case, the email templates are located in the src/emails folder.

{
    "scripts": {
        "email": "email dev --dir src/emails"
    }
}

Run npm run email in your terminal. This command starts the React Email development server, allowing you to choose from the existing templates. Alternatively, you can create an emails folder containing an index.tsx file and copy this email template into it.

import {
    Body,
    Column,
    Container,
    Head,
    Heading,
    Hr,
    Html,
    Link,
    Preview,
    Section,
    Text,
    Row,
} from "@react-email/components";
import * as React from "react";

const EmailTemplate = () => (
    <Html>
        <Head />
        <Preview>Hello World</Preview>
        <Body style={main}>
            <Container style={container}>
                <Section style={header}>
                    <Row>
                        <Column style={headerContent}>
                            <Heading style={headerContentTitle}>Hello World</Heading>
                        </Column>
                    </Row>
                </Section>

                <Section style={content}>
                    <Text style={paragraph}>Hey Emil,</Text>
                    <Text style={paragraph}>Cool</Text>
                </Section>
            </Container>

            <Section style={footer}>
                <Text style={footerText}>
                    You&apos;re receiving this email because your subscribed to Newsletter
                    App
                </Text>

                <Hr style={footerDivider} />
                <Text style={footerAddress}>
                    <strong>Newsletter App</strong>, &copy;{" "}
                    <Link href='https://novu.co'>Novu</Link>
                </Text>
            </Section>
        </Body>
    </Html>
);

export default EmailTemplate;

const main = {
    backgroundColor: "#f3f3f5",
    fontFamily: "HelveticaNeue,Helvetica,Arial,sans-serif",
};

const headerContent = { padding: "20px 30px 15px" };

const headerContentTitle = {
    color: "#fff",
    fontSize: "27px",
    fontWeight: "bold",
    lineHeight: "27px",
};

const paragraph = {
    fontSize: "15px",
    lineHeight: "21px",
    color: "#3c3f44",
};

const divider = {
    margin: "30px 0",
};

const container = {
    width: "680px",
    maxWidth: "100%",
    margin: "0 auto",
    backgroundColor: "#ffffff",
};

const footer = {
    width: "680px",
    maxWidth: "100%",
    margin: "32px auto 0 auto",
    padding: "0 30px",
};

const content = {
    padding: "30px 30px 40px 30px",
};

const header = {
    borderRadius: "5px 5px 0 0",
    display: "flex",
    flexDireciont: "column",
    backgroundColor: "#2b2d6e",
};

const footerDivider = {
    ...divider,
    borderColor: "#d6d8db",
};

const footerText = {
    fontSize: "12px",
    lineHeight: "15px",
    color: "#9199a1",
    margin: "0",
};

const footerLink = {
    display: "inline-block",
    color: "#9199a1",
    textDecoration: "underline",
    fontSize: "12px",
    marginRight: "10px",
    marginBottom: "0",
    marginTop: "8px",
};

const footerAddress = {
    margin: "4px 0",
    fontSize: "12px",
    lineHeight: "15px",
    color: "#9199a1",
};

At this point, you should have an email template ready to integrate into Novu Echo. 🚀

To get started with Novu Echo, close the React Email server, and run the code snippet below. It opens the Novu Dev Studio in your browser.

npx novu-labs@latest echo

Create an echo folder containing a client.ts file within the Next.js app folder and copy this code snippet into the file.

import { Echo } from "@novu/echo";
import { renderEmail } from "@/emails";

interface EchoProps {
    step: any;
    payload: {
        subject: string;
        message: string;
        firstName: string;
    };
}
export const echo = new Echo({
    apiKey: process.env.NEXT_PUBLIC_NOVU_API_KEY!,
    devModeBypassAuthentication: process.env.NODE_ENV === "development",
});

echo.workflow(
    "newsletter",
    async ({ step, payload }: EchoProps) => {
        await step.email(
            "send-email",
            async () => {
                return {
                    subject: `${payload ? payload?.subject : "No Subject"}`,
                    body: renderEmail(payload),
                };
            },
            {
                inputSchema: {
                    type: "object",
                    properties: {},
                },
            }
        );
    },
    {
        payloadSchema: {
            type: "object",
            properties: {
                message: {
                    type: "string",
                    default: "This is a test message from Newsletter",
                },
                subject: { type: "string", default: "Message from Newsletter App" },
                firstName: { type: "string", default: "User" },
            },
            required: ["message", "subject", "firstName"],
            additionalProperties: false,
        },
    }
);

The code snippet defines a Novu notification workflow named newsletter, which accepts a payload containing the email subject, message, and the recipient's first name. This payload contains the necessary data for the React Email template.

Update the React Email template to receive and display the payload data:

const EmailTemplate = ({
    message,
    subject,
    firstName,
}: {
    message: string;
    subject: string;
    firstName: string;
}) => (
    <Html>
        <Head />
        <Preview>{subject}</Preview>
        <Body style={main}>
            <Container style={container}>
                <Section style={header}>
                    <Row>
                        <Column style={headerContent}>
                            <Heading style={headerContentTitle}>{subject}</Heading>
                        </Column>
                    </Row>
                </Section>

                <Section style={content}>
                    <Text style={paragraph}>Hey {firstName},</Text>
                    <Text style={paragraph}>{message}</Text>
                </Section>
            </Container>

            <Section style={footer}>
                <Text style={footerText}>
                    You&apos;re receiving this email because your subscribed to Newsletter
                    App
                </Text>

                <Hr style={footerDivider} />
                <Text style={footerAddress}>
                    <strong>Newsletter App</strong>, &copy;{" "}
                    <Link href='https://novu.co'>Novu</Link>
                </Text>
            </Section>
        </Body>
    </Html>
);

//👇🏻 passes the payload as props into the component
export function renderEmail(inputs: {
    message: string;
    subject: string;
    firstName: string;
}) {
    return render(<EmailTemplate {...inputs} />);
}

The <EmailTemplate/> component accepts the email's message, subject, and recipient's first name as props to replace the existing variables within the component.

Next, you need to create an API route for Novu Echo. Within the api folder, create an email folder containing a route.ts file and copy the provided code snippet below into the file.

import { serve } from "@novu/echo/next";
import { echo } from "../../echo/client";

export const { GET, POST, PUT } = serve({ client: echo });

Make sure you have run npx novu-labs@latest echo in your terminal. This command will automatically open the Novu Dev Studio at this URL: http://localhost:2022/ in your browser. Here, you can select the exact API endpoint you served Novu Echo and preview your email templates before adding to the Novu Cloud Platform.

Once you can preview your email template within the Novu Dev Studio, you can save the workflow to your Novu dashboard. Click the Sync to Cloud button at the top right side of the page.

The Sync to Cloud button triggers a pop-up that provides instructions on how to push your workflow to the Novu Cloud.

To proceed, run the following code snippet in your terminal. This will generate a unique URL representing a local tunnel between your development environment and the cloud environment.

npx localtunnel --port 3000

Copy the generated link along with your Echo API endpoint into the Echo Endpoint field and then click the Create Diff button.

https://<LOCAL_TUNNEL_URL>/<ECHO_API_ENDPOINT>

Afterward, scroll down and select Deploy Changes to push the workflow to the cloud environment.

You can also preview your workflow on the Novu Cloud by clicking the Test your workflows link from the notification alert. Congratulations! Your workflow has been successfully deployed.

Now, you can start sending emails via the workflow. Open the api/send API route and copy the provided code snippet below into the route.ts file.

import { NextRequest, NextResponse } from "next/server";
import { SubscribersData } from "../../util";
import { Novu } from "@novu/node";

//👇🏻 Novu SDK for sending emails
const novu = new Novu(process.env.NOVU_API_KEY!);

export async function POST(req: NextRequest) {
    const { subject, message, subscribers } = await req.json();

    subscribers.forEach(async (subscriber: SubscribersData) => {
        const { data } = await novu.trigger("newsletter", {
            to: {
                subscriberId: subscriber.subscriberId,
                email: subscriber.email,
                firstName: subscriber.firstName,
                lastName: subscriber.lastName,
            },
            payload: {
                subject,
                message,
                firstName: subscriber.firstName,
            },
        });
        console.log(data.data);
    });

    return NextResponse.json(
        {
            message: "Emails sent successfully",
            success: true,
        },
        { status: 200 }
    );
}

The code snippet uses the Novu SDK to send an email to all the subscribers within the application.

Congratulations! 🎉You've completed the project for this tutorial.

Conclusion

So far, you've learnt how to implement multiple authentication methods with Firebase, store and retrieve data from Firebase, create email templates with React Email, and send them via Novu.

You also learned how to leverage the code-first notification workflow approach to build notification workflows within the code while giving your non-technical teammates full control over content and behaviour.

Novu is your best choice to add various notification channels to your applications, including Chat, SMS, Email, Push, and In-app notifications.

The source code for this tutorial is available here:
https://github.com/novuhq/newsletter-app-with-novu-echo

Thank you for reading!

How To Build Your Own Newsletter App? p.1

Emil Pearce — Thu, 16 May 2024 11:02:07 +0000

TL;DR

In this 2-part tutorial, I'll guide you through building a newsletter application that allows users to subscribe to a mailing list using a Google or GitHub account.

The application stores the user's details (email, first and last names) to Firebase, enabling the admin user to send notifications of beautifully designed email templates to every subscriber within the application using Novu.

You'll learn how to:

implement Firebase Google, GitHub, and Email/Password authentication to your applications
Save and fetch data from Firebase Firestore
Create and modify email templates in the Novu Dev Studio
Send email templates using the Novu

Building the application interface with Next.js

In this section, I'll walk you through building the user interface for the newsletter application.

First, let's set up a Next.js project. Open your terminal and run the following command:

npx create-next-app newsletter-app

Follow the prompts to select your preferred configuration settings. For this tutorial, we'll use TypeScript and the Next.js App Router for navigation.

Install the React Icons package, which allows us to use various icons within the application.

npm install react-icons

The application pages are divided into two parts - the subscriber routes and admin routes.

Subscriber Routes:
- / - The application home page that displays GitHub and Google sign-in buttons for user authentication.
- /subscribe - This page notifies users that they have successfully subscribed to the newsletter.
Admin Routes:
- /admin - This route displays the admin sign-up and login buttons.
- /admin/register - Here, admins can access the sign-up form to create a new admin account.
- /admin/login - Existing admin users can log into the application using their email and password.
- /admin/dashboard - Admin users can access this route to view all subscribers and manage the creation and sending of newsletters.

The Subscriber Routes

Copy the code snippet below into app/page.tsx file. It displays the GiHub and Google sign-in buttons.

"use client";
import { useState } from "react";
import { FaGoogle, FaGithub } from "react-icons/fa";

export default function Home() {
    const [loading, setLoading] = useState<boolean>(false);

    const handleGoogleSignIn = () => {
        setLoading(true);
        //👉🏻 Firebase Google Sign in function
    };

    const handleGithubSignIn = () => {
        setLoading(true);
        //👉🏻 Firebase GitHub Sign in function
    };

    return (
        <main className='flex h-screen flex-col p-8 items-center justify-center'>
            <h2 className='text-3xl font-bold mb-6'>Sign up to the Newsletter</h2>

            <button
                className='py-3 px-6 flex items-center justify-center rounded-md border-gray-600 border-2 w-3/5 mb-4 text-lg hover:bg-gray-800 hover:text-gray-50'
                disabled={loading}
            >
                <FaGithub className='inline-block mr-2' />
                {loading ? "Signing in..." : "Sign Up with Github"}
            </button>

            <button
                className='py-3 px-6 flex items-center justify-center rounded-md border-gray-600 border-2 w-3/5 mb-4 text-lg hover:bg-gray-800 hover:text-gray-50'
                disabled={loading}
            >
                <FaGoogle className='inline-block mr-2' />
                {loading ? "Signing in..." : "Sign Up with Google"}
            </button>
        </main>
    );
}

Create a subscribe folder within the app directory. Inside the subscribe folder, add a page.tsx file and a layout.tsx file.

cd app
mkdir subscribe && cd subscribe
touch page.tsx layout.tsx

To indicate that the user has successfully subscribed to the newsletter, copy and paste the following code snippet into the subscribe/page.tsx file:

"use client";

export default function Subscribe() {
    const handleSignOut = () => {
        //👉🏻 signout the subscriber
    };

    return (
        <main className='p-8 min-h-screen flex flex-col items-center justify-center'>
            <h3 className='text-3xl font-bold mb-4'>You&apos;ve Subscribed!</h3>
            <button
                className='bg-black text-gray-50 px-8 py-4 rounded-md w-[200px]'
                onClick={handleSignOut}
            >
                Back
            </button>
        </main>
    );
}

Finally, update the subscribe/layout.tsx file with the following changes to set the page title to Subscribe | Newsletter Subscription:

import type { Metadata } from "next";
import { Sora } from "next/font/google";

const sora = Sora({ subsets: ["latin"] });

//👇🏻 changes the page title
export const metadata: Metadata = {
    title: "Subscribe | Newsletter Subscription",
    description: "Generated by create next app",
};

export default function RootLayout({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    return (
        <html lang='en'>
            <body className={sora.className}>{children}</body>
        </html>
    );
}

The Admin Routes

Create an admin folder within the app directory. Inside the admin folder, add a page.tsx file to represent the Admin home page and a layout.tsx file to display the page title.

cd app
mkdir admin && cd admin
touch page.tsx layout.tsx

Copy the code snippet below into the admin/page.tsx file. It displays the links to the Admin Sign-up and Login pages.

import Link from "next/link";

export default function Admin() {
    return (
        <main className='flex min-h-screen flex-col items-center justify-center p-8'>
            <h2 className='text-3xl font-bold mb-6'>Admin Panel</h2>

            <Link
                href='/admin/register'
                className='py-3 px-6 flex items-center justify-center rounded-md border-gray-600 border-2 w-3/5 mb-4 text-lg hover:bg-gray-800 hover:text-gray-50'
            >
                Sign Up as an Admin
            </Link>

            <Link
                href='/admin/login'
                className='py-3 px-6 flex items-center justify-center rounded-md border-gray-600 border-2 w-3/5 mb-4 text-lg hover:bg-gray-800 hover:text-gray-50'
            >
                Log in as an Admin
            </Link>
        </main>
    );
}

Update the page title by copying this code snippet into the admin/layout.tsx file.

import type { Metadata } from "next";
import { Sora } from "next/font/google";

const sora = Sora({ subsets: ["latin"] });

export const metadata: Metadata = {
    title: "Admin | Newsletter Subscription",
    description: "Generated by create next app",
};

export default function RootLayout({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    return (
        <html lang='en'>
            <body className={sora.className}>{children}</body>
        </html>
    );
}

Next, you need to create the Admin Register, Login, and Dashboard pages. Therefore, create the folders containing a page.tsx file.

cd admin
mkdir login register dashboard
cd login && page.tsx
cd ..
cd register && page.tsx
cd ..
cd dashboard && page.tsx

Within the register/page.tsx file, copy and pasted the code snippet provided below. The code block displays the sign-up form where users can enter their email and password to create an admin user account.

"use client";
import React, { useState } from "react";
import { useRouter } from "next/navigation";
import Link from "next/link";

export default function Register() {
    const [email, setEmail] = useState<string>("");
    const [disabled, setDisabled] = useState<boolean>(false);
    const [password, setPassword] = useState<string>("");

    const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        setDisabled(true);
        //👉🏻 admin sign up function
    };
    return (
        <main className='flex min-h-screen flex-col items-center justify-center p-8'>
            <h2 className='font-bold text-3xl text-gray-700 mb-3'>Admin Sign Up</h2>
            <form
                className='md:w-2/3 w-full flex flex-col justify-center'
                onSubmit={handleSubmit}
            >
                <label htmlFor='email' className='text-lg'>
                    Email
                </label>
                <input
                    type='email'
                    id='email'
                    value={email}
                    onChange={(e) => setEmail(e.target.value)}
                    required
                    className='w-full py-3 px-6 border-gray-600 border-[1px] rounded-md mb-4'
                />

                <label htmlFor='password' className='text-lg'>
                    Password
                </label>
                <input
                    type='password'
                    id='password'
                    required
                    value={password}
                    onChange={(e) => setPassword(e.target.value)}
                    className='w-full py-3 px-6 border-gray-600 border-[1px] rounded-md mb-4'
                />

                <button
                    className='py-3 px-6 rounded-md bg-black text-gray-50'
                    disabled={disabled}
                >
                    Register
                </button>
                <p className='text-md mt-4 text-center'>
                    Already have an account?{" "}
                    <Link href='/admin/login' className='text-blue-500'>
                        Log in
                    </Link>
                </p>
            </form>
        </main>
    );
}

Update the login/page.tsx file similarly to the admin register page. It accepts the user's email and password and logs the user into the application.

"use client";
import React, { useState } from "react";
import Link from "next/link";

export default function Login() {
    const [email, setEmail] = useState<string>("");
    const [password, setPassword] = useState<string>("");
    const [disabled, setDisabled] = useState<boolean>(false);

    const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        setDisabled(true);
        //👉🏻 log user into the application
    };

    return (
        <main className='flex min-h-screen flex-col items-center justify-center p-8'>
            <h2 className='font-bold text-3xl text-gray-700 mb-3'>Admin Login</h2>
            <form
                className='md:w-2/3 w-full flex flex-col justify-center'
                onSubmit={handleSubmit}
            >
                <label htmlFor='email' className='text-lg'>
                    Email
                </label>
                <input
                    type='email'
                    id='email'
                    value={email}
                    onChange={(e) => setEmail(e.target.value)}
                    placeholder='test@gmail.com'
                    required
                    className='w-full py-3 px-6 border-gray-600 border-[1px] rounded-md mb-4'
                />

                <label htmlFor='password' className='text-lg'>
                    Password
                </label>
                <input
                    type='password'
                    id='password'
                    required
                    placeholder='test123'
                    value={password}
                    onChange={(e) => setPassword(e.target.value)}
                    className='w-full py-3 px-6 border-gray-600 border-[1px] rounded-md mb-4'
                />

                <button
                    className='py-3 px-6 rounded-md bg-black text-gray-50'
                    disabled={disabled}
                >
                    Log in
                </button>
                <p className='text-md mt-4 text-center'>
                    Don&apos;t have an account?{" "}
                    <Link href='/admin/register' className='text-blue-500'>
                        Create one
                    </Link>
                </p>
            </form>
        </main>
    );
}

Finally, let's create the admin dashboard page. It displays all the available subscribers and a form enabling admin users to create and view the existing newsletters.

Copy the code snippet below into the dashboard/page.tsx file.

"use client";
import { useState } from "react";
import Link from "next/link";
import Newsletters from "@/components/Newsletters";
import SubscribersList from "@/components/SubscribersList";

type Subscriber = {
    id: string;
    data: {
        email: string;
        firstName: string;
        lastName: string;
        topics: string[];
    };
};

export default function Dashboard() {
    const [subscribers, setSubscribers] = useState<Subscriber[]>([]);
    const [toggleView, setToggleView] = useState<boolean>(false);
    const handleToggleView = () => setToggleView(!toggleView);

    const fetchAllSubscribers = async () => {
        //👉🏻 fetch all subscribers
    };

    const handleLogout = () => {
        //👉🏻 sign user out
    };

    return (
        <div className='flex w-full min3-h-screen relative'>
            <div className='lg:w-[15%] border-r-2 lg:flex hidden flex-col justify-between min-h-[100vh]'>
                <nav className='fixed p-4 pb-8 flex flex-col justify-between h-screen'>
                    <div className='flex flex-col space-y-4'>
                        <h3 className='text-2xl font-bold text-blue-500 mb-6'>Dashboard</h3>
                        <Link
                            href='#subscribers'
                            onClick={handleToggleView}
                            className={`${
                                toggleView ? "" : "bg-blue-400 text-blue-50"
                            }  p-3 mb-2 rounded-md`}
                        >
                            Subscribers
                        </Link>
                        <Link
                            href='#newsletters'
                            onClick={handleToggleView}
                            className={`${
                                !toggleView ? "" : "bg-blue-400 text-blue-50"
                            }  p-3 mb-2 rounded-md`}
                        >
                            Newsletters
                        </Link>
                    </div>

                    <button className='text-red-500 block mt-10' onClick={handleLogout}>
                        Log out
                    </button>
                </nav>
            </div>

            <main className='lg:w-[85%] w-full bg-white h-full p-4'>
                <div className='flex items-center lg:justify-end justify-between mb-3'>
                    <Link
                        href='#'
                        onClick={handleToggleView}
                        className='lg:hidden block text-blue-700'
                    >
                        {!toggleView ? "View Newsletters" : "View Subscribers"}
                    </Link>
                    <button
                        className='bg-red-500 text-white px-5 py-3 rounded-md lg:hidden block'
                        onClick={handleLogout}
                    >
                        Log Out
                    </button>
                </div>
                <div>
                    {toggleView ? (
                        <Newsletters />
                    ) : (
                        <SubscribersList subscribers={subscribers} />
                    )}
                </div>
            </main>
        </div>
    );
}

From the code snippet above, we have two components: the Newsletters and the SubscribersList.

The Newsletters component renders the existing newsletters and a form that allows the admin to create new ones. The SubscribersList component displays all the existing subscribers within the application.

Therefore, create a components folder that contains the Newsletters and SubscribersList components within the app folder.

cd app
mkdir components && cd components
touch SubscribersList.tsx Newsletters.tsx

Copy the code snippet below into the SubscribersList.tsx. It accepts the existing subscribers' data as a prop and renders it within a table.

"use client";

type Subscriber = {
    id: string;
    data: {
        email: string;
        firstName: string;
        lastName: string;
        topics: string[];
    };
};

export default function SubscribersList({
    subscribers,
}: {
    subscribers: Subscriber[];
}) {
    return (
        <main className='w-full'>
            <section className='flex items-center justify-between mb-4'>
                <h2 className='font-bold text-2xl mb-3'>All Subscribers</h2>
            </section>
            <div className='w-full'>
                <table className='w-full'>
                    <thead>
                        <tr>
                            <th className='py-3'>First Name</th>
                            <th className='py-3'>Last Name</th>
                            <th className='py-3'>Email Address</th>
                        </tr>
                    </thead>
                    <tbody>
                        {subscribers.map((subscriber) => (
                            <tr key={subscriber.id}>
                                <td className='py-3'>{subscriber.data.firstName}</td>
                                <td className='py-3'>{subscriber.data.lastName}</td>
                                <td className='py-3'>{subscriber.data.email}</td>
                            </tr>
                        ))}
                    </tbody>
                </table>
            </div>
        </main>
    );
}

Lastly, update the Newsletters.tsx component to display the newsletter creation form and display the existing newsletters.

"use client";
import React, { useEffect, useState } from "react";

export default function Newsletters() {
    const [recipients, setRecipients] = useState<string[]>([]);
    const [subject, setSubject] = useState<string>("");
    const [message, setMessage] = useState<string>("");
    const [disabled, setDisable] = useState<boolean>(false);
    const [subscribers, setSubscribers] = useState<SubscribersData[]>([]);
    const [newsLetters, setNewsletters] = useState<string[]>([]);

    const handleSendNewsletter = (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        emailNewsletter();
    };

    const emailNewsletter = async () => {
        //👉🏻 send newsletter
    };

    const fetchRecipients = async () => {
        //👉🏻 fetch all subscribers
    };

    const fetchNewsLetters = async () => {
        //👉🏻 fetch all newsletters
    };

    useEffect(() => {
        fetchRecipients();
        fetchNewsLetters();
    }, []);

    return (
        <main className='w-full'>
            <h2 className='font-bold text-2xl mb-4'>Create Campaign</h2>
            <form onSubmit={handleSendNewsletter} className='mb-8'>
                <label htmlFor='subject'>Subject</label>
                <input
                    type='text'
                    id='subject'
                    value={subject}
                    required
                    onChange={(e) => setSubject(e.target.value)}
                    className='w-full px-4 py-3 border-[1px] border-gray-600 rounded-sm mb-3'
                />

                <label htmlFor='recipients'>Recipients</label>
                <input
                    type='text'
                    id='recipients'
                    className='w-full px-4 py-3 border-[1px] border-gray-600 rounded-sm mb-3'
                    disabled
                    readOnly
                    value={recipients.join(", ")}
                />
                <label htmlFor='message'>Message</label>
                <textarea
                    id='message'
                    rows={5}
                    value={message}
                    required
                    onChange={(e) => setMessage(e.target.value)}
                    className='w-full px-4 py-3 border-[1px] border-gray-600 rounded-sm'
                ></textarea>
                <button
                    className='bg-blue-500 text-white py-3 px-6 rounded my-3'
                    disabled={disabled}
                >
                    {disabled ? "Sending..." : "Send Newsletter"}
                </button>
            </form>

            <h2 className='font-bold text-2xl '>Recent Newsletters</h2>
            <div className='flex flex-col gap-4'>
                {newsLetters.map((item, index) => (
                    <div
                        className='flex justify-between items-center bg-gray-100 p-4'
                        key={index}
                    >
                        <h3 className='font-bold text-md'>{item}</h3>
                        <button className='bg-green-500 text-gray-50 px-4 py-2 rounded-md'>
                            Sent
                        </button>
                    </div>
                ))}
            </div>
        </main>
    );
}

Congratulations!🥳 You've successfully completed the user interface for the application.

In the upcoming section, you'll learn how to connect the application to a Firebase backend and effectively manipulate data within the application.

How to add Firebase authentication to a Next.js application

In this section, you'll learn how to implement multiple authentication methods using Firebase within your application.

Subscribers will have the option to subscribe or sign in using either a Google or GitHub account, while Admin users will be able to sign in using the Email and Password authentication method.

Setting up a Firebase project

Visit the Firebase console and sign in with a Gmail account.

Create a Firebase project and select the </> icon to create a new Firebase web app.

Provide your app name and register it.

Install the Firebase SDK in your Next.js project by running the code snippet below.

npm install firebase

Create a firebase.ts file at the root of your Next.js project and copy the Firebase configuration code for your app into the file.

import { initializeApp, getApps } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import { getAuth, GoogleAuthProvider, GithubAuthProvider } from "firebase/auth";

const firebaseConfig = {
    apiKey: "******",
    authDomain: "**********",
    projectId: "********",
    storageBucket: "******",
    messagingSenderId: "**********",
    appId: "********",
    measurementId: "********",
};
//👇🏻 gets the app config
const app =
    getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];
//👇🏻 creates a Firebase Firestore instance
const db = getFirestore(app);
//👇🏻 creates a Firebase Auth instance
const auth = getAuth(app);
//👇🏻 creates a Google & GitHub Auth instance
const googleProvider = new GoogleAuthProvider();
const githubProvider = new GithubAuthProvider();
//👇🏻 export them for use within the application
export { db, auth, googleProvider, githubProvider };

Before you can add Firebase Authentication to your application, you need to set it up in your Firebase console.

To do this, navigate to the left-hand side panel, select Build, and then click on Authentication to add Firebase Authentication to your project.

Lastly, enable the Google and Email/Password authentication methods.

Add Google authentication to Next.js

First, create a util.ts file within the app folder and copy the provided code snippet into the file.

import { signInWithPopup } from "firebase/auth";
import { auth } from "../../firebase";

//👇🏻 Split full name into first name and last name
export const splitFullName = (fullName: string): [string, string] => {
    const [firstName, ...lastNamePart] = fullName.split(" ");
    return [firstName, lastNamePart.join(" ")];
};

//👇🏻 Handle Sign in with Google and Github
export const handleSignIn = (provider: any, authProvider: any) => {
    signInWithPopup(auth, provider)
        .then((result) => {
            const credential = authProvider.credentialFromResult(result);
            const token = credential?.accessToken;
            if (token) {
                const user = result.user;
                const [first_name, last_name] = splitFullName(user.displayName!);
                console.log([first_name, last_name, user.email]);
            }
        })
        .catch((error) => {
            const errorCode = error.code;
            const errorMessage = error.message;
            console.error({ errorCode, errorMessage });
            alert(`An error occurred, ${errorMessage}`);
        });
};

The code snippet enables users to sign into the application via Google or GitHub authentication. It accepts authentication providers as parameters and logs the user's email, first name, and last name to the console after a successful authentication process.

Next, you can execute the handleSignIn function within the app/page.tsx file when a user clicks the Sign Up with Google or GitHub buttons.

import { GoogleAuthProvider, GithubAuthProvider } from "firebase/auth";
import { googleProvider, githubProvider } from "../../firebase";
import { handleSignIn } from "./util";

const handleGoogleSignIn = () => {
    setLoading(true);
    handleSignIn(googleProvider, GoogleAuthProvider);
};

const handleGithubSignIn = () => {
    setLoading(true);
    handleSignIn(githubProvider, GithubAuthProvider);
};

Add GitHub authentication to Next.js

Before the GitHub authentication method can work as expected, you need to create a GitHub OAuth App.

Once you've created the GitHub OAuth App, copy the client ID and client secret from the app settings. You'll need these credentials to activate the GitHub authentication method within the application.

Go back to the Firebase Console. Enable the GitHub sign-in method and paste the client ID and secret into the input fields provided. Additionally, add the authorisation callback URL to your GitHub app.

Congratulations! You've successfully added GitHub and Google authentication methods to the application. Next, let's add the Email/Password authentication for Admin users.

Add email and password authentication to Next.js

Before we proceed, ensure you have enabled the email/password sign-in method within the Firebase project. Then, execute the functions below when a user signs up and logs in as an admin user.

import {
    createUserWithEmailAndPassword,
    signInWithEmailAndPassword,
} from "firebase/auth";
import { auth } from "../../firebase";

//👇🏻 Admin Firebase Sign Up Function
export const adminSignUp = async (email: string, password: string) => {
    try {
        const userCredential = await createUserWithEmailAndPassword(
            auth,
            email,
            password
        );
        const user = userCredential.user;
        if (user) {
            //👉🏻 sign up successful
        }
    } catch (e) {
        console.error(e);
        alert("Encountered an error, please try again");
    }
};

//👇🏻 Admin Firebase Login Function
export const adminLogin = async (email: string, password: string) => {
    try {
        const userCredential = await signInWithEmailAndPassword(
            auth,
            email,
            password
        );
        const user = userCredential.user;
        if (user) {
            //👉🏻 log in successful
        }
    } catch (e) {
        console.error(e);
        alert("Encountered an error, please try again");
    }
};

The provided code snippets include functions for admin user sign-up (adminSignUp) and login (adminLogin) using Firebase authentication. You can trigger these functions when a user signs up or logs in as an admin user.

You can sign users (admin and subscribers) out of the application using the code snippet below.

import { signOut } from "firebase/auth";
import { auth } from "../../firebase";

//👇🏻 Firebase Logout Function
export const adminLogOut = async () => {
    signOut(auth)
        .then(() => {
            //👉🏻 sign out successful
        })
        .catch((error) => {
            console.error({ error });
            alert("An error occurred, please try again");
        });
};

Congratulations! You've completed the authentication process for the application. You can read through the concise documentation if you encounter any issues.

How to interact with Firebase Firestore

In this section, you'll learn how to save and retrieve data from Firebase Firestore by saving newsletters, subscribers, and admin users to the database.

Before we proceed, you need to add the Firebase Firestore to your Firebase project.

Create the database in test mode, and pick your closest region.

After creating your database, select Rules from the top menu bar, edit the rules, and publish the changes. This enables you to make requests to the database for a longer period of time.

Congratulations!🎉 Your Firestore database is ready.

Saving subscribers’ data to the database

After a user subscribes to the newsletter, you need to save their first name, last name, email, and user ID to Firebase. To do this, execute the saveToFirebase function after a subscriber successfully signs in via the GitHub or Google sign-in method.

import { auth, db } from "../../firebase";
import { addDoc, collection, getDocs } from "firebase/firestore";

export type SubscribersData = {
    firstName: string;
    lastName: string;
    email: string;
    id: string;
};

//👇🏻 Save the subscriber data to Firebase
const saveToFirebase = async (subscriberData: SubscribersData) => {
    try {
        //👇🏻 checks if the subscriber already exists
        const querySnapshot = await getDocs(collection(db, "subscribers"));
        querySnapshot.forEach((doc) => {
            const data = doc.data();
            if (data.email === subscriberData.email) {
                window.location.href = "/subscribe";
                return;
            }
        });
        //👇🏻 saves the subscriber details
        const docRef = await addDoc(collection(db, "subscribers"), subscriberData);
        if (docRef.id) {
            window.location.href = "/subscribe";
        }
    } catch (e) {
        console.error("Error adding document: ", e);
    }
};

The saveToFirebase function validates if the user is not an existing subscriber to prevent duplicate entries before saving the subscriber's data to the database.

To differentiate between existing subscribers and admin users within the application, you can save admin users to the database.

Execute the provided function below when a user signs up as an admin.

import { db } from "../../firebase";
import { addDoc, collection } from "firebase/firestore";

//👇🏻 Add Admin to Firebase Database
const saveAdmin = async (email: string, uid: string) => {
    try {
        const docRef = await addDoc(collection(db, "admins"), { email, uid });
        if (docRef.id) {
            alert("Sign up successful!");
            window.location.href = "/admin/dashboard";
        }
    } catch (e) {
        console.error("Error adding document: ", e);
    }
};

Next, update the admin log-in function to ensure that the user's data exists within the admin collection before granting access to the application.

import { auth, db } from "../../firebase";
import { addDoc, collection, getDocs, where, query } from "firebase/firestore";

//👇🏻 Admin Firebase Login Function
export const adminLogin = async (email: string, password: string) => {
    try {
        const userCredential = await signInWithEmailAndPassword(
            auth,
            email,
            password
        );
        const user = userCredential.user;
        //👇🏻 Email/Password sign in successful
        if (user) {
            //👇🏻 check if the user exists within the database
            const q = query(collection(db, "admins"), where("uid", "==", user.uid));
            const querySnapshot = await getDocs(q);
            const data = [];
            querySnapshot.forEach((doc) => {
                data.push(doc.data());
            });
            if (data.length) {
                window.location.href = "/admin/dashboard";
                alert("Log in successful!");
            }
        }
    } catch (e) {
        console.error(e);
        alert("Encountered an error, please try again");
    }
};

To ensure that only authenticated users can access the Admin dashboard, Firebase allows you to retrieve the current user's data at any point within the application. This enables us to protect the Dashboard page from unauthorised access and listen to changes in the user's authentication state.

import { onAuthStateChanged } from "firebase/auth";
import { auth } from "../firebase";

export default function Dashboard() {
    const router = useRouter();

    useEffect(() => {
        onAuthStateChanged(auth, (user) => {
            if (!user) {
                //👉🏻 redirect user to log in form
                router.push("/");
            }
        });
    }, [router]);
}

Congratulations on making it thus far! 🎉 In the upcoming sections, you'll learn how to create and send beautifully designed newsletters to subscribers using Novu Echo and React Email.