Forem: Jessica Chowdhury

Error Management Magic: Introducing the Sentry Plugin for Payload

Jessica Chowdhury — Thu, 27 Jul 2023 13:38:15 +0000

This integration brings Sentry's real-time error tracking, alerting, and performance monitoring features directly into your Payload project. We want to empower your developers to diagnose and resolve issues with unmatched efficiency.

yarn add @payloadcms/plugin-sentry
// OR
npm i @payloadcms/plugin-sentry

What is error tracking and why does it matter?

Error tracking is the process of meticulously collecting and analyzing errors that occur within your application. With a strong error tracking solution, you open the door to a plethora of benefits that will elevate the overall quality of your project.

A good error tracking solution will allow you to...

Prioritize and address errors ensuring that the most important errors are fixed first
Identify recurring errors and patterns earlier and prevent them from snowballing
Save valuable time when it comes to debugging and troubleshooting errors
Increase application reliability and reduce downtime
Improve the overall developer and user experience

Ultimately, error tracking serves as a key component in driving the overall quality of your software. By addressing issues promptly, improving reliability, and optimizing the development process, you can deliver a product that takes software development to new heights.

Sentry: The Error Monitoring Powerhouse

Sentry is a leading, feature-rich, open-source platform for error and performance monitoring. With minimal setup, you can start capturing valuable data from your application and access it through Sentry's comprehensive and easy to use dashboard.

Here is a glance at their awesome features:

Error tracking: Get detailed reports with stack traces, environment data, and user info
Performance monitoring: Including user interactions, network requests, and other performance metrics
Release tracking and health monitoring: Keep tabs on releases and monitor application health with ease
Cross-project visibility: Sentry lets you manage and monitor errors across all multiple apps from one central platform
Custom dashboards: Access the metrics that matter most to you and personalize the dashboard to your needs
Notifications and email alerts: Add and customize alerts so you'll be the first to know when something is happening

And that's just the tip of the iceberg. Sentry's features empowers you to manage errors with extreme efficiency, saving time and resources while delivering a top user experience.

Step-by-Step Plugin Integration Guide

Let’s walkthrough the setup process for the Sentry-Payload plugin:

1. Installing the Plugin

Navigate to your Payload app then install the plugin using Yarn or NPM:

yarn add @payloadcms/plugin-sentry
// OR
npm i @payloadcms/plugin-sentry

2. Creating a Sentry Account

If you don't have a Sentry account already, it's time to create one. Head over to Sentry and create an account. The registration process is straightforward and will only take a few minutes.

3. Locating Your DSN

The DSN (Data Source Name) is a unique identifier that connects your application to Sentry. After creating your Sentry account, you can find your project's DSN in the project settings or configuration section.

4. Add DSN to your Payload Config file

By this step, you should have the plugin installed and your DSN identifier ready. Navigate to your payload.config() file and add the plugin along with your DSN:

const config = buildConfig({
  plugins: [
    sentry({
      dsn: 'your-dsn-string-here',
    }),
  ]
});

5. Configure additional options (not required)

These options allow you to fine-tune the Sentry integration to your specific needs:

init : ClientOptions | optional

Sentry allows a variety of options to be passed into the Sentry.init() function, see the full list of options here.

requestHandler : RequestHandlerOptions | optional

Accepts options that let you decide what data should be included in the event sent to Sentry, checkout the options here.

captureErrors: number[] | optional

By default, Sentry.errorHandler will capture only errors with a status code of 500 or higher. To capture additional error codes, pass the values as numbers in an array.

Pass any of these options to the plugin like so:

const config = buildConfig({
  plugins: [
    sentry({
      dsn: 'your-dsn-string-here',
      options: {
        init: {
          debug: true,
          environment: 'development',
          tracesSampleRate: 1.0,
        },
        requestHandler: {
          serverName: false,
          user: ["email"],
        },
        captureErrors: [400, 403, 404],
      }
    }),
  ]
});

Take it for a spin

Once you have the plugin installed and configured, Sentry will be ready to start capturing errors for you. So let’s take this plugin for a test drive by intentionally triggering an error:

Start your Payload app with yarn dev
Navigate to the login page in your browser
Instead of using your valid credentials, enter an incorrect password
This should throw the following error: AuthenticationError: The email or password provided is incorrect
Go to sentry.io and select the project associated with the DSN in your payload.config()
See the new error in your dashboard, click into it for more detail

Wrap Up

A robust error tracking solution is crucial to delivering a reliable and performant application. Sentry provides developers with the ultimate toolbox, comprehensive error and performance monitoring, custom dashboards, real-time notifications and much more.

This plugin aims to make integrating Sentry into your Payload project a breeze. With 3 lines of code, you can instantly improve your error handling workflow. Give it a go and as always, reach out to us if you have any questions or feedback! Happy tracking 👋

Payload + Nodemailer: Free and Extensible Email Integration

Jessica Chowdhury — Fri, 26 May 2023 15:45:03 +0000

Email is a necessary evil in our lives. We don’t love it, but we need it.

With Payload, you don't have to abandon what you're already familiar with. Stick to your trusty SMTP if you like to keep things simple. Or, if you're a fan of Gmail or Outlook, go ahead and integrate them with ease. You can even bring in other powerful email service tools like SendGrid, Resend, HubSpot and more.

Integrating email with Payload is free, flexible and highly extensible. No matter what kind of emails you need to send – from newsletters, transactional and marketing emails, to those crucial authentication emails – we've got you covered.

In this post, we’ll walk through the process of configuring email with Payload and cover everything you need to get up and running. Let’s dive in!

How it works

Payload utilizes Nodemailer to produce a versatile email transporter which can then be used anywhere in your application.

For those who are new to Nodemailer, it is a powerful module in the Node.js ecosystem that greatly simplifies the process of sending email. We recommend taking a look at the Nodemailer docs if you want to learn more.

If you have used Nodemailer before, this process will be familiar. Simply create a new transport and pass it to the email property in your payload.init() function.

Once you add your email configuration, you can send emails from anywhere in your application simply by calling Payload.sendEmail({}). Neat, huh?

Configuration

The email property takes the following options:

fromName - required
fromAddress - required
logMockCredentials - will output your credentials to the console on startup
transportOptions - pass in your options and let Payload create the transport for you
transport - manual create a transporter using nodemailer.createTransport({})

Important: You only need to use transportOptions OR transport in your email configuration. Not both.

There are two ways to create a Nodemailer-compatible transport:

Define your transportOptions and Payload do it for you
Manually configure a transport or import a separate package to do this for you

To get setup, navigate to where you are calling payload.init(), this is usually in `src/server.ts.

After adding your email options, your payload.init() should look something like this:

export const email = {
  fromName: 'Admin',
  fromAddress: 'admin@example.com',
  logMockCredentials: true,
  transportOptions: {},   
  transport: {},
}

const start = async (): Promise<void> => {
  await payload.init({
    secret: process.env.PAYLOAD_SECRET,
    mongoURL: process.env.MONGODB_URI,
    express: app,
    email,
  })

  app.listen(8000)
}

start()

Important: We always recommend storing sensitive data as environment variables and not directly in your code to prevent security vulnerabilities.

Mock email handler

If you do not provide a transport or transportOptions, Payload will initialize an ethereal capture service. Ethereal is a free email caching service which captures all outbound emails. Using this service can be really useful for testing emails when you’re working in a development environment.

To use this service, logMockCredentials must be set to true. This will output the ethereal credentials to your console after startup, you will then use these to login to ethereal.email and view any emails that are sent during development.

transportOptions

Pass any valid Nodemailer options to transportOptions and Payload will create the transporter for you.

You can use transportOptions to configure:

SMTP

export const email = {
  fromName: 'Admin',
  fromAddress: 'admin@example.com',
  transportOptions: { 
    host: process.env.SMTP_HOST,
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_PASS
    },
    port: 587,
    secure: false,
  }
}

An email service

Nodemailer will automatically provide the connection details (host, port, etc) for several well known email services. For example if you want to use Gmail, you simply need to provide the service name like this:

export const email = {
  fromName: 'Admin',
  fromAddress: 'admin@example.com',
  transportOptions: {
    service: 'gmail',
    auth: {
      user: process.env.GMAIL_USER,
      pass: process.env.GMAIL_PASS,
    },
  }
}

An external transport, a nodemailer plugin or similar

import nodemailerSendgrid from 'nodemailer-sendgrid'

export const email = {
  fromName: 'Admin',
  fromAddress: 'admin@example.com',
  transportOptions: nodemailerSendgrid({
    apiKey: process.env.SENDGRID_API_KEY,
  }),
}

Nodemailer has created packages that integrate popular email vendors for you, such as SendGrid:

transport

This option allows you to manually create a transport, this supports SMTP and email services.

You can make use of nodeMailer.createTransport({}) for support of well known email services and browse this list of options that you can define.

import nodemailer from 'nodemailer'
import payload from 'payload'

const transport = await nodemailer.createTransport({
  service: 'outlook',
  auth: {
    user: process.env.OUTLOOK_USER,
    pass: process.env.OUTLOOK_PASS,
  },
})

const email = {
  fromName: 'Admin',
  fromAddress: 'admin@example.com',
  logMockCredentials: true,
  // Passes your custom transport
  transport,
}

More examples of using nodeMailer.createTransport({}) can be found in the Nodemailer documentation.

Sending Email

Once you have configured your transporter, you can start sending emails from anywhere inside your Payload project by calling payload.sendEmail({}).

payload.sendEmail({}) takes properties of to, from, subject, and html:

import payload from 'payload'

payload.sendEmail({
  from: 'sender@example.com',
  to: 'receiver@example.com',
  subject: 'Message subject title',
  html: '<p>HTML based message</p>',
})

Dynamic Email Content

There are many ways to include data directly from your project into your emails. Whether it is using hooks, making API requests, fetching data from globals or anything else you can think of.

For example, sending order details when there is a new submission to the Orders collection:

import payload from 'payload'
import type { CollectionConfig } from 'payload/types'

const Orders: CollectionConfig = {
  slug: 'orders',
  hooks: {
    afterChange: [
      ({ doc, operation, req }) => {
        const { customerEmail, items, total } = doc
        if (operation === 'create') {
          req.payload.sendEmail({
            to: customerEmail,
            from: 'sender@example.com',
            subject: 'Welcome To Payload',
            html: `<h1>Thank you for your order!</h1>
              <p>Here is your order summary:</p>
              <ul>
                ${items.map(item => `<li>${item.name} - ${item.price}</li>`)}
              </ul>
              <p>Total: ${total}</p>
            `,
          })
        }
      },
    ],
  },
  fields: [],
}

export default Orders

Automatically trigger email dispatch

Payload’s collection and field hooks allow you to define specific conditions which will trigger an email to be sent.

Like sending an email every time you receive a newsletter signup:

import payload from 'payload'
import type { CollectionConfig } from 'payload/types'

const NewsletterSignups: CollectionConfig = {
  slug: 'newsletter-signups',
  hooks: {
    afterChange: [
      ({ doc, operation, req }) => {
        if (operation === 'create') {
          req.payload.sendEmail({
            to: doc.email,
            from: 'sender@example.com',
            subject: 'You have joined our newsletter list!',
            html: '<p>Thanks for signing up</p>',
          })
        }
      },
    ],
  },
  fields: [],
}

export default NewsletterSignups

Or sending a welcome email to new users:

import payload from 'payload'
import type { CollectionConfig } from 'payload/types'

const Users: CollectionConfig = {
  slug: 'users',
  auth: true,
  hooks: {
    afterChange: [
      ({ doc, operation }) => {
        if (operation === 'create') {
          payload.sendEmail({
            to: doc.email,
            from: 'sender@example.com',
            subject: 'Welcome To Payload',
            html: '<b>Hey there!</b><br/>Welcome to Payload!',
          })
        }
      },
    ],
  },
  fields: [],
}

export default Users

Authentication Emails

Payload makes auth-enabled collections super simple to integrate with email by handling forgotPassword and verify for you.

Each auth-enabled collection has forgotPassword and verify options that you can pass generateEmailSubject and generateEmailHTML functions to. The function accepts one argument containing { req, token, user }.

import payload from 'payload'
import type { CollectionConfig } from 'payload/types'

const Users: CollectionConfig = {
  slug: 'users',
  auth: {
    verify: {
      generateEmailSubject: () => 'Verify your email',
      generateEmailHTML:  ({ token }) => `<p>Verify your account here ${process.env.PAYLOAD_PUBLIC_SITE_URL}/verify?token=${token}.</p>`,
    },
    forgotPassword: {
      generateEmailSubject: () => 'Reset your password',
      generateEmailHTML: ({ token }) => `<p>Reset your password here ${process.env.PAYLOAD_PUBLIC_SITE_URL}/reset-password?token=${token}.</p>`,
      },
    },
  },
  fields: [],
}

export default Users

Templates

Payload doesn't ship a default HTML templating engine, so you are free to add whatever suits you best.

Make your email templates highly dynamic by using Handlebars, a templating language that combines HTML, plain text and expressions. The expressions are included in the html template surrounded by double curly braces.

<table border="0" width="100%">
  <tbody>
      <td>
        <!-- HEADLINE -->
        <h1>{{headline}}</h1>
      </td>
    </tr>
    <tr>
      <td>
        <!-- CONTENT -->
        {{{content}}}
      </td>
    </tr>
  </tbody>
</table>

Here is a simple but powerful function that ties everything together in one function:

import fs from 'fs'
import Handlebars from 'handlebars'
import inlineCSS from 'inline-css'
import path from 'path'
import payload from 'payload'

const template = fs.readFileSync(path.join(__dirname, 'template.html'), 'utf8')
const getHTML = Handlebars.compile(template)

export const sendEmailWithTemplate = async (args): Promise<any> => {
  const { from, to, subject, data } = args

  const templateData = {
    ...data,
    apiURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
    siteURL: process.env.PAYLOAD_PUBLIC_SITE_URL,
  }
  const preInlinedCSS = getHTML(templateData)

  const html = await inlineCSS(preInlinedCSS, {
    url: ' ',
    removeStyleTags: false,
  })

  await payload.sendEmail({
    from,
    to,
    subject,
    html,
  })

  return null
}

The template.html file that is being used in sendEmailWithTemplate can be any HTML file of your choice. You can find this template in our email example, feel free to use this as a starter template and add your own custom CSS.

Example

We have an example repo where you can see these code snippets being used and try them out in real time.

Wrap Up

Payload aims to provide developers with a powerful but simple solution when it comes to configuring and managing email. By harnessing the capabilities of Nodemailer, we can offer flexibility in choosing email providers and accommodate various email needs.

I hope this post provides value and gives you a good introduction to email integration with Payload.

Always feel free to reach out if you have any questions or feedback!

Learn More

Like what we're doing? Give us a star on GitHub

We're trying to change the CMS status quo by delivering editors with a great experience, but first and foremost, giving developers a CMS that they don't hate working with. All of our new features are meant to be extensible and work simply and sanely.