​
Introduction

In this guide, you’ll learn how to send email notifications using the React email package. But before we jump into it, let’s first take a look at the prerequisites!

​
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.
  1. 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!
npx create-novu-app --api-key=<YOUR_API_KEY>
  1. Once you execute this command, you’ll be asked to give your project a name. I’ll keep the default my-novu-app but you can choose your own.

Give your app a name

  1. You’ll then be asked if you want to use React-email or not. You can choose to install it at this step itself or proceed with No and then install it later. I’m choosing the default No option.

Choose if you want to install React email or not

  1. 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

  1. Once this installation is complete, simply cd into the directory and start your app using the npm run dev command, and your app will be served on localhost:4000
Make sure that the port 4000 isn’t already being used!
You’ll now have a NextJS app running on 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

Here’s how the Dev Studio looks on the first run:

Echo Dev Studio on the first run

You’ll notice that it asks for an Bridge endpoint at the bottom. Novu Framework requires a single HTTP endpoint (/api/novu or similar) to be exposed by your application. This endpoint is used to receive events from our Worker Engine. We have more on Bridge endpoint in our docs.
You can view the Bridge Endpoint as a webhook endpoint that Novu will call when it needs to retrieve contextual information for a given subscriber and notification.
Just enter the full URL of your Bridge Endpoint. In our case, it is http://localhost:4000/api/echo

Enter Echo endpoint URL

Once you do, you’ll see a green checkmark alongside the URL input box and a green connected highlight at the top right corner.

​
Installing and configuring React Email

If you opted for installing React Email in our CLI set-up process, you can skip installing it again.
Integrating React Email with Novu in our NextJS app is quite straightforward. Following are the steps to get it installed and configured:
  1. Simply run the following command to install it like any other npm package:
  npm i @react-email/components react-email
Once installed, proceed to write an email template in the next step
  1. To write an email template, you can look over some of the examples in the React Email documentation to get inspiration. In our case, this is the template:
import {
  Body,
  Button,
  Container,
  Column,
  Head,
  Hr,
  Html,
  Img,
  Link,
  render,
  Row,
  Section,
  Text,
  Tailwind,
} from "@react-email/components";
import * as React from "react";

interface VercelInviteUserEmailProps {
  username?: string;
  userImage?: string;
  invitedByUsername?: string;
  invitedByEmail?: string;
  teamName?: string;
  teamImage?: string;
  inviteLink?: string;
  inviteFromIp?: string;
  showJoinButton?: boolean;
  inviteFromLocation?: string;
  buttonText?: string
}

const baseUrl = process.env.VERCEL_URL
  ? `https://${process.env.VERCEL_URL}`
  : "";

export const VercelInviteUserEmail = ({
  username,
  userImage,
  invitedByUsername,
  invitedByEmail,
  teamName,
  teamImage,
  inviteLink,
  inviteFromIp,
  inviteFromLocation,
  showJoinButton,
  buttonText
}: VercelInviteUserEmailProps) => {

  return (
    <Html>
      <Head />
      <Tailwind>
        <Body className="bg-white my-auto mx-auto font-sans px-2">
          <Container className="border border-solid border-[#eaeaea] rounded my-[40px] mx-auto p-[20px] max-w-[465px]">
            <Section className="mt-[32px]">
              <Img
                src={`https://react-email-demo-ndjnn09xj-resend.vercel.app/static/vercel-logo.png`}
                width="40"
                height="37"
                alt="Vercel"
                className="my-0 mx-auto"
              />
            </Section>
            <Text className="text-black text-[14px] leading-[24px]">
              Hello {username},
            </Text>
            <Text className="text-black text-[14px] leading-[24px]">
              <strong>{invitedByUsername}</strong> (
              <Link
                href={`mailto:${invitedByEmail}`}
                className="text-blue-600 no-underline"
              >
                {invitedByEmail}
              </Link>
              ) has invited you to the <strong>{teamName}</strong> team on{" "}
              <strong>Vercel</strong>.
            </Text>
            <Section>
              <Row>
                <Column align="right">
                  <Img
                    className="rounded-full"
                    src={userImage}
                    width="64"
                    height="64"
                  />
                </Column>
                <Column align="center">
                  <Img
                    src={`https://react-email-demo-ndjnn09xj-resend.vercel.app/static/vercel-arrow.png`}
                    width="12"
                    height="9"
                    alt="invited you to"
                  />
                </Column>
                <Column align="left">
                  <Img
                    className="rounded-full"
                    src={teamImage}
                    width="64"
                    height="64"
                  />
                </Column>
              </Row>
            </Section>
            {showJoinButton && (
              <Section className="text-center mt-[32px] mb-[32px]">
                <Button
                  className="bg-[#000000] rounded text-white text-[12px] font-semibold no-underline text-center px-5 py-3"
                  href={inviteLink}
                >
                  {buttonText}
                </Button>
              </Section>
            )}
            <Text className="text-black text-[14px] leading-[24px]">
              or copy and paste this URL into your browser:{" "}
              <Link href={inviteLink} className="text-blue-600 no-underline">
                {inviteLink}
              </Link>
            </Text>
            <Hr className="border border-solid border-[#eaeaea] my-[26px] mx-0 w-full" />
            <Text className="text-[#666666] text-[12px] leading-[24px]">
              This invitation was intended for{" "}
              <span className="text-black">{username}</span>. This invite was
              sent from <span className="text-black">{inviteFromIp}</span>{" "}
              located in{" "}
              <span className="text-black">{inviteFromLocation}</span>. If you
              were not expecting this invitation, you can ignore this email. If
              you are concerned about your account's safety, please reply to
              this email to get in touch with us.
            </Text>
          </Container>
        </Body>
      </Tailwind>
    </Html>
  );
};

VercelInviteUserEmail.PreviewProps = {
  username: "alanturing",
  userImage: `${baseUrl}/static/vercel-user.png`,
  invitedByUsername: "Alan",
  invitedByEmail: "alan.turing@example.com",
  teamName: "Enigma",
  teamImage: `${baseUrl}/static/vercel-team.png`,
  inviteLink: "https://vercel.com/teams/invite/foo",
  inviteFromIp: "204.13.186.218",
  inviteFromLocation: "São Paulo, Brazil",
} as VercelInviteUserEmailProps;

export default VercelInviteUserEmail;

export function renderReactEmail(input: any, payload: any) {
  return render(<VercelInviteUserEmail {...input}{...payload} />);

}
  1. And as final step, we need to define the workflow that uses the template defined above.
export const newSignup = workflow('new-signup', async ({ step, payload }) => {
  // Send a welcome email
  await step.email('send-email', async (inputs) => {
    return {
      subject: `Welcome to Novu, ${payload.username}`,
      body: renderReactEmail(inputs, payload),
    };
  }, {
    inputSchema: {
      type: "object",
      properties: {
        showJoinButton: { type: "boolean", default: true },
        buttonText: { type: "string", default: "Join the team" },
        userImage: {
          type: "string",
          default: "https://react-email-demo-bdj5iju9r-resend.vercel.app/static/vercel-user.png",
          format: "uri",
        },
        invitedByUsername: { type: "string", default: "Alan" },
        invitedByEmail: {
          type: "string",
          default: "alan.turing@example.com",
          format: "email",
        },
        teamName: { type: "string", default: "Team Awesome" },
        teamImage: {
          type: "string",
          default: "https://react-email-demo-bdj5iju9r-resend.vercel.app/static/vercel-team.png",
          format: "uri",
        },
        inviteLink: {
          type: "string",
          default: "https://vercel.com/teams/invite/foo",
          format: "uri",
        },
        inviteFromIp: { type: "string", default: "204.13.186.218" },
        inviteFromLocation: {
          type: "string",
          default: "São Paulo, Brazil",
        },
      },
    },
  });
  // JSON Schema for validation and type-safety. Zod, and others coming soon.
}, { payloadSchema: { properties: { text: { type: 'string' } } } });
Once you do this, you’ll see this workflow, the steps in the workflow, step inputs, payload variables and, the rendered view of this workflow on the Echo Dev Studio:

Echo Dev Studio now picks up the workflow we just created

Here, from the Dev Studio, you or your peers can change things like the text of a button, toggle visibility of a button, static text content, etc, and have it synced with the cloud with the 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 is used for dynamic content that changes from one notification to another based on events occurring in your system.
  • Step Inputs are for static elements or predefined options that non-technical team members can modify without altering the codebase.
  • Payload is controlled by developers and passed dynamically through the novu.trigger method.
  • Step Inputs are defined by developers but are meant 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 Echo instance, you need to supply an Echo 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. The create-novu-app command sets up localtunnel for you. Running the npm 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: 
// using ngrok 
ngrok http http://localhost:<YOUR_EDGE_PORT>
In our case, the app is running on port 4000 so we’ll use: 
ngrok http http://localhost:4000
This will create a tunnel and you’ll see something like this in the terminal:

ngrok has done its magic

Remember, the exact URL (/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://0536-2409-40f2-1039-43e1-3053-d98e-c276-ee5.ngrok-free.app/api/echo So, we’ll enter this Bridge URL:

Enter the Bridge URL in the Dev Studio

And create diff:

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 you’ve created has a blue lightning bolt icon. That icon signifies that the corresponding workflow has been created with Novu Framework:

You'll see the workflow created using Novu Framework with the blue lightning bolt icon

Simply open the workflow and you can send a test email from there.
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

This is the workflow test email in my inbox:

Workflow test email in my inbox

Once tested, you can simply have this workflow triggered whenever you want. For instance, a typical use case is to have a workflow triggered when an event occurs. To replicate it, I’ve attached a handler function that triggers this workflow when the submit event fires: Here’s a simple replication of the stipulated scenario: 
"use client"
import Image from "next/image";
import styles from "./page.module.css";
import React, { useState } from "react";
import axios from "axios";

export default function Home() {

  const [email, setEmail] = useState('')
  const [username, setUsername] = useState('')

  const onClickHandler = async (e: React.FormEvent<HTMLFormElement>) => {
    try {
      e.preventDefault();
      await fetch("/api/users", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          email: email,
          username: username,
        }),
      });

      // console.log('working fine');
    } catch (error) {
      console.error('Error:', error);
    }
  };
  return (
    <main style={{ height: '100vh', display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
      <form onSubmit={(e) => onClickHandler(e)}>
        <input
          placeholder="Enter email id"
          onChange={(e) => setEmail(e.target.value)}
          style={{
            // Add your CSS-in-JS styles here
            padding: '0.5rem',
            marginBottom: '1rem',
            borderRadius: '0.25rem',
            border: '1px solid #ccc',
            width: '100%',
            boxSizing: 'border-box',
          }}
        />
        <input
          placeholder="Enter the name of invitee"
          onChange={(e) => setUsername(e.target.value)}
          style={{
            // Add your CSS-in-JS styles here
            padding: '0.5rem',
            marginBottom: '1rem',
            borderRadius: '0.25rem',
            border: '1px solid #ccc',
            width: '100%',
            boxSizing: 'border-box',
          }}
        />
        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center' }}>

          <button
            style={{
              // Add your CSS-in-JS styles here
              padding: '0.5rem 1rem',
              backgroundColor: '#4CAF50',
              color: 'white',
              border: 'none',
              borderRadius: '0.25rem',
              cursor: 'pointer',
            }}
          >
            Submit
          </button>
        </div>
      </form>
    </main>
  );
}
And the corresponding route it hits: 
import { Novu } from '@novu/node';

const novu = new Novu('<Your Novu API Key>');

export async function POST(request: Request) {
  const res = await request.json();

  await novu.trigger('<Workflow name>', {
    to: {
      subscriberId: '<subscriber ID>',
    },
    payload: {
      email: res.email,
      username: res.username,
    },
  });

  console.log('triggered')
  return Response.json({ success: true });
}

​
More workflow examples

Creating workflows with Novu Framework is a breeze. Here are a couple of other examples from React email docs created with Novu Framework:
  1. AWS Email verification example

AWS verification example

  1. Apple invoice email example

Apple invoice email example

​
Conclusion

So there you go! This is how you create workflows using Novu Framework and deploy your changes seamlessly to the Novu cloud. You can check out the code for a sample demo app. Once you’ve built the workflow, you might want read one of our other guides on how to empower product teams to manage notification workflows.
Don’t forget to share your workflows with us and as always, hit us up on Discord with any questions you might have!