Nascent Plasticine Materialist

    @seedcompany/nestjs-email
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.5 • Public • Published

    @SeedCompany/nestjs-email

    A NestJS library to generate emails via JSX and send them via AWS SES

    How it works

    The rendering is powered by mjml with a React wrapper.
    This allows email templates & components to be created in a typesafe way while having the complexities of email HTML handled by mjml.

    The generated HTML runs through html-to-text to automatically create a text version of the email.
    Where needed, this ouput can be customized with our <InText> and <HideInText> components.

    After that a MIME message is composed via emailjs.
    This merges the HTML, text, attachments, & headers (from, to, etc.) to a string.

    With the MIME message finalized it is sent to SES via their v3 SDK.
    Their SDK allows for automatic configuration; compared to SMTP which needs to be configured with an explicit server, username, and password.

    All of this is wrapped in an NestJS module for easy integration.

    There's also an open option to open rendered HTML in browser, which can be useful for development.

    Setup

    Simple static

    EmailModule.forRoot({
      from: 'dev@foo.com', // "Dev <dev@foo.com>" format also works
      send: true, // Actually send email. It's assumed this is not always wanted aka dev.
      global: true, // Optionally allow EmailService to be used globally without importing module
    })

    See EmailModuleOptions for all options.

    Async Configuration

    More complex setups can use async configuration (standard to NestJS packages)

    Factory function example

    EmailModule.forRootAsync({
      useFactory: async (foo: FooService) => ({
        from: await foo.getFromAddress(),
      }),
      import: [FooService],
    })

    Options class example

    EmailModule.forRootAsync({
      useClass: EmailConfig,
      // or
      useExisting: EmailConfig,
    })
    @Injectable()
    export class EmailConfig implements EmailOptionsFactory {
      async createEmailOptions() {
        return {
          from: '',
        };
      }
    }

    Usage

    Define a template

    import * as Mjml from '@seedcompany/nestjs-email/templates';
    import { Mjml as MjmlRoot } from 'mjml-react';
    import * as React from 'react';
    
    export function ForgotPassword({ name, url }: { name: string, url: string }) {
      return (
        <MjmlRoot lang="en">
          <Mjml.Head>
            {/* Title also sets the subject */}
            <Mjml.Title>Forgot Password</Mjml.Title>
          </Mjml.Head>
          <Mjml.Body>
    
            <Mjml.Section>
              <Mjml.Column padding={0}>
                <Mjml.Text fontSize={24}>
                  Hey {name}, passwords are hard
                </Mjml.Text>
              </Mjml.Column>
            </Mjml.Section>
    
            <Mjml.Section>
              <Mjml.Column>
                <Mjml.Text>
                  If you requested this, confirm the password change
                </Mjml.Text>
                <Mjml.Button href={url}>CONFIRM</Mjml.Button>
              </Mjml.Column>
            </Mjml.Section>
    
          </Mjml.Body>
        </MjmlRoot>
      );
    }

    This is a single component to show the complete picture. In actual usage it makes more sense to break this up into smaller components, just like would be done with React UIs.

    For example, an <Email> wrapping component could be created to wrap Mjml root, Head, Body, setup theme, etc.

    A <Heading> component could turn the first section into a one liner.

    Call it

    import { Injectable } from '@nestjs/common';
    import { EmailService } from '@seedcompany/nestjs-email';
    import { ForgotPassword } from './forgot-password.template';
    
    @Injectable()
    export class UserService {
      constructor(private email: EmailService) {}
    
      async forgotPassword(emailAddress: string) {
        const user = await lookupByEmail(emailAddress);
    
        await this.email.send(user.email, ForgotPassword, {
          // type safe parameters per template
          name: user.name,
          url: 'https://foo.com/signed-url/...',
        });
      }
    }

    Keywords

    none

    Install

    npm i @seedcompany/nestjs-email

    DownloadsWeekly Downloads

    13

    Version

    2.0.5

    License

    MIT

    Unpacked Size

    45.8 kB

    Total Files

    39

    Last publish

    Collaborators

    • michaelm220
    • carsonfull