# Preview templates in current directory
npx @ainsleydev/email-templates preview

# Preview templates in a specific directory
npx @ainsleydev/email-templates preview ./emails

# Use a custom port
npx @ainsleydev/email-templates preview ./emails --port=3001

The preview server will:

Automatically discover all .tsx and .jsx files in the specified directory
Render them with the default theme
Serve them at http://localhost:3000/<template-name>

Note: Your template files must export a React component that accepts a theme prop.

Quick start

1. Create your email template

// emails/ForgotPassword.tsx
import { BaseEmail, Heading, Text, Section, Button, generateStyles } from '@ainsleydev/email-templates'
import type { EmailTheme } from '@ainsleydev/email-templates'

interface ForgotPasswordProps {
  theme: EmailTheme
  user: { firstName: string }
  resetUrl: string
}

export const ForgotPasswordEmail = ({ theme, user, resetUrl }: ForgotPasswordProps) => {
  const styles = generateStyles(theme)

  return (
    <BaseEmail theme={theme} previewText="Reset your password">
      <Heading style={styles.heading}>
        Hello, {user.firstName}!
      </Heading>
      <Text style={styles.text}>
        We received a request to reset your password. Click the button below to continue.
      </Text>
      <Section style={{ textAlign: 'center' }}>
        <Button href={resetUrl} style={styles.button}>
          Reset Password
        </Button>
      </Section>
    </BaseEmail>
  )
}

2. Render the template

import { renderEmail } from '@ainsleydev/email-templates'
import { ForgotPasswordEmail } from './emails/ForgotPassword'

const html = await renderEmail({
  component: ForgotPasswordEmail,
  props: {
    user: { firstName: 'John' },
    resetUrl: 'https://example.com/reset/token123',
  },
})

// Send via your email service.
await emailService.send({
  to: 'user@example.com',
  subject: 'Reset your password',
  html,
})

Theme customisation

Using partial overrides

const html = await renderEmail({
  component: ForgotPasswordEmail,
  props: {
    user: { firstName: 'Jane' },
    resetUrl: 'https://example.com/reset/abc',
  },
  theme: {
    branding: {
      companyName: 'My Company',
      logoUrl: 'https://mycompany.com/logo.png',
      logoWidth: 150,
      footerText: 'All rights reserved.',
      websiteUrl: 'https://mycompany.com',
    },
    colours: {
      text: {
        action: '#0066cc', // Custom link colour.
      },
    },
  },
})

Creating a complete theme

import { defaultTheme, type EmailTheme } from '@ainsleydev/email-templates'

const customTheme: EmailTheme = {
  ...defaultTheme,
  branding: {
    companyName: 'Custom Corp',
    logoUrl: 'https://custom.com/logo.png',
    logoWidth: 200,
    footerText: 'All rights reserved.',
    websiteUrl: 'https://custom.com',
  },
  colours: {
    ...defaultTheme.colours,
    text: {
      ...defaultTheme.colours.text,
      action: '#ff0000',
    },
  },
}

// Use in all your emails.
const html = await renderEmail({
  component: MyEmail,
  props: myProps,
  theme: customTheme,
})

Usage with Payload CMS

Payload CMS allows you to customise email templates for authentication emails.

import { buildConfig } from 'payload'
import { renderEmail } from '@ainsleydev/email-templates'
import { ForgotPasswordEmail } from './emails/ForgotPassword'
import { VerifyAccountEmail } from './emails/VerifyAccount'

export default buildConfig({
  email: {
    fromName: 'My App',
    fromAddress: 'noreply@myapp.com',
    // Configure your email transport.
  },
  collections: [
    {
      slug: 'users',
      auth: {
        forgotPassword: {
          generateEmailHTML: async ({ token, user }) => {
            return renderEmail({
              component: ForgotPasswordEmail,
              props: {
                user: { firstName: user.firstName },
                resetUrl: `${process.env.FRONTEND_URL}/reset-password?token=${token}`,
              },
              theme: {
                branding: {
                  companyName: 'My App',
                  logoUrl: `${process.env.FRONTEND_URL}/logo.png`,
                },
              },
            })
          },
        },
        verify: {
          generateEmailHTML: async ({ token, user }) => {
            return renderEmail({
              component: VerifyAccountEmail,
              props: {
                user: { firstName: user.firstName },
                verifyUrl: `${process.env.FRONTEND_URL}/verify?token=${token}`,
              },
            })
          },
        },
      },
    },
  ],
})

React Email components

All React Email components are re-exported for convenience:

import {
  Html, Head, Preview, Body, Container, Section, Row, Column,
  Heading, Text, Button, Link, Img, Hr,
  // ...and more
} from '@ainsleydev/email-templates'

// Use them directly in your templates:
<Heading>Welcome</Heading>
<Text>Hello world</Text>
<Button href="...">Click here</Button>

See React Email documentation for full component API.

API

`renderEmail(options)`

Renders an email template component to HTML string.

Options:

component - Your React component that accepts theme prop
props - Props to pass to your component (excluding theme)
theme - Optional theme overrides
plainText - Render as plain text instead of HTML (default: false)

Returns: Promise<string> - HTML or plain text string

`BaseEmail`

Base layout component with logo, content area, and footer.

Props:

theme: EmailTheme - Theme configuration
previewText?: string - Email preview text
children: React.ReactNode - Email content

`generateStyles(theme)`

Generates common style objects from theme configuration.

Returns: Object with heading, text, button, hr, etc. styles

`defaultTheme`

Default theme configuration based on ainsley.dev design system.

`mergeTheme(partial)`

Merges partial theme with default theme.

Examples

See the test file for more examples of creating custom templates.

Development

# Install dependencies.
pnpm install

# Run tests.
pnpm test

# Build package.
pnpm build

# Format code.
pnpm format

# Lint code.
pnpm lint

TODO

Go CLI support - Add CLI command for rendering templates from Go via exec.Command. This would allow Go applications to use the same email templates without needing a Node.js runtime dependency.

Licence

MIT ainsley.dev