How to send notifications with Next.js and MJML
Leverage MJML package to send email notifications
Introduction
This guide will walk you through how to send notifications with MJML and Novu. You can check out the code for a sample demo app.Pre-requisites
- A Novu account
- Node installed on your machine
- A working NextJS development environment
Get started with Novu Framework
Novu Framework is a “notifications as code” approach that enables developers to define workflows as functions and integrate them with their preferred libraries for email, SMS, and chat generation.- To get started with Novu Framework, just run this command in your terminal, it’ll scaffold a new NextJS project with Novu Framework and we’ll be ready to roll!
- Once you execute this command, you’ll be asked to give your project a name. I’ll keep the default
my-novu-appbut you can choose your own.
Give your app a name
- You’ll then be asked if you want to use React-email or not. Since, we’ll be using MJML, I’m choosing the default ‘No’ option.
Choose if you want to install React email or not
- After this step, all the dependencies will be installed and you will be able to start using Novu Framework.
Let all the dependencies get installed
- Once this installation is complete, simply cd into the directory and start your app using the
npm run devcommand, and your app will be served onlocalhost:4000
Make sure that the port 4000 isn’t already being used!
http://localhost:4000 and you can make changes to your app as you see fit. Let’s now move to the meaty stuff - using Novu Framework in a NextJS app and the magic of Dev Studio.
Echo Dev Studio
The Echo Dev Studio is a companion app to the Echo Client SDK. Its goal is to provide a local environment that lives near your code. To launch the dev studio locally you can run:npx novu-labs@latest echo. The Dev Studio will be started by default on port 2022, and accessible via: http://localhost:2022
Echo Dev Studio runs on 'localhost:2022' by default. Here I’m already using port 2022 so it is starting on a different port but we recommend ensuring that port 2022 is free
Echo Dev Studio on the first run
Echo endpoint at the bottom. Novu Echo requires
a single HTTP endpoint (/api/echo or similar) to be exposed by your application.
This endpoint is used to receive events from our Worker Engine. We have more on Novu
endpoint in our docs.
You can view the Echo Endpoint as a webhook endpoint that Novu will call when
it needs to retrieve contextual information for a given subscriber and
notification.
http://localhost:4000/api/echo
Enter Echo endpoint URL
connected highlight at the top right corner.
Installing and configuring MJML
Integrating MJML with Novu in our NextJS app is quite straightforward, with just one small caveat. Following are the steps to get it installed and configured:- Simply run the following command to install it like any other npm package:
Once installed, you need to keep in mind that, MJML doesn’t play very nice
with newer web technologies such as Next.js that we’re using today. In order
to overcome some hurdles, we need to use the
require statement when
importing MJML in our files, such as when defining the template.- To write an email template, you can look over some of the examples in the MJML documentation to get inspiration from. In our case, this is the template:
- And as final step, we need to define the workflow that uses the template defined above.
Echo Dev Studio now picks up the workflow we just created
Sync to Cloud button.
Payload vs Step Inputs
Notice that in the Echo dev studio above, we’ve used payload as well as step inputs. Here’s how you can decide if you need either or both:| Payload | Step Inputs |
|---|---|
| is used for dynamic content that changes from one notification to another based on events occurring in your system. | are used for static elements or predefined options that non-technical team members can modify without altering the codebase. |
| is controlled by developers and passed dynamically through the novu.trigger method. | are defined by developers but aremeant to be utilized and modified by non-technical peers. |
| Payload examples include User ID, Post ID, Comment, Order ID, 2FA token, etc., which are likely to change with each notification. | Step Inputs examples include the text of a button, whether a section should be shown, static text content, etc., which are generally static but configurable elements. |
| Payload modifications are made in the code by developers at the time of triggering a notification. | Step Inputs can be modified directly in the UI, offering a no-code solution for non-technical team members to make changes. |
| Payload data is passed during the novu.trigger method and is part of the dynamic data handling process within notification workflows. | Step Inputs are predefined in the workflow configuration and can be adjusted through the Echo Dev Studio, affecting how notifications are rendered without changing the workflow logic. |
Syncing with the cloud, with the click of a button
Once done with the workflow, now we need to sync it to the cloud. Fortunately, Novu Framework makes it a breeze to sync changes from the local machine to the cloud and it all happens with a click of a button. To enable our cloud environment to talk to your local Bridge instance, you need to supply an Bridge Endpoint URL. This sets up a communication channel between our cloud environment and your local instance. To allow Novu to communicate with your local machine a tunnel will need to be generated. Running thenpm run dev script in the project launches both the Bridge application and the tunnel solution. The tunnel URL shows up in the console output.
You can also use a tool like ngrok:
ngrok has done its magic
/api/novu or similar) you expose in your application for
handling Novu Framework requests is what you’d consider the Bridge URL.
This URL would be the endpoint within your application’s domain where Novu’s Worker Engine sends requests to fetch notification content or subscriber details dynamically. In our case, it is this: https://faec-2409-40f2-3c-3b57-400e-a7f7-1fc0-1e5.ngrok-free.app/api/echo
So, we’ll enter this Bridge URL:
Enter the Echo URL in the Dev Studio
Echo Dev Studio will create a diff for you
Testing our workflow
Once you’ve synced your changes in the previous step, you’ll see a notification that says ‘Sync complete’ and you can now go to Novu Cloud using the ‘Test your workflows’ link and trigger a notification.
Test your workflow will take you to Novu Cloud
You'll see the workflow created using Echo with the blue lightning bolt icon
Make sure that all the expected payload variables and step inputs are being
sent in their respective fields!
Enter the respective data and test your workflow
Workflow test email in my inbox
submit event fires:
Here’s a simple replication of the stipulated scenario: