142 lines
6.1 KiB
Markdown
142 lines
6.1 KiB
Markdown
# Email Templates (React-Email)
|
|
|
|
**Package:** `packages/mail/src/templates-react/`
|
|
**Status:** active (Phase 10 task #75)
|
|
**Replaces:** `packages/mail/src/templates/transactional.ts` (deprecated)
|
|
|
|
## Overview
|
|
|
|
Transactional emails are React components. Every template is rendered
|
|
deterministically to `{ html, text }` via `react-dom/server` and
|
|
delivered through the standard Mailjet/queue provider chain.
|
|
|
|
We chose React components over the legacy string-template approach
|
|
for three reasons:
|
|
|
|
1. **XSS-safety by default** — React escapes interpolated values, so
|
|
we cannot accidentally forget an `escapeHtml` call when a new
|
|
prop is introduced. The old monolithic file had a recurring
|
|
audit finding around manual escaping.
|
|
2. **Component reuse** — header, footer, button, info-box, and
|
|
eyebrow are shared across templates. Brand-theming threads
|
|
through a single `MailBrand` prop instead of token-replacement
|
|
on raw HTML strings.
|
|
3. **Live preview** — `pnpm --filter @hivegrid/mail preview` boots
|
|
a local HTTP server that renders every template with realistic
|
|
sample data so designers can iterate without triggering live
|
|
email sends.
|
|
|
|
## Adding a new template
|
|
|
|
1. **Create the component** in `packages/mail/src/templates-react/transactional/<TemplateName>.tsx`.
|
|
Accept a `brand: MailBrand` prop plus the data the template needs.
|
|
Compose with `TransactionalScaffold` for the standard layout.
|
|
Avoid `dangerouslySetInnerHTML` — it is banned by code review.
|
|
2. **Validate URLs** — every CTA must go through `<Button>`. The
|
|
component throws `InvalidActionUrlError` for anything other than
|
|
`https://` or `mailto:` URLs.
|
|
3. **Register the template** in
|
|
`packages/mail/src/templates-react/render.ts`:
|
|
- Add the name to `ReactTransactionalTemplateName`
|
|
- Add the prop type to `ReactTemplatePropsMap`
|
|
- Add the component to the `COMPONENTS` map
|
|
4. **Add a snapshot test** at
|
|
`packages/mail/src/templates-react/transactional/<TemplateName>.test.tsx`
|
|
covering: default render (HTML + text snapshots), tenant brand
|
|
override, XSS-safety on at least one user-supplied prop, and
|
|
URL-validation error if the template takes an `actionUrl`.
|
|
5. **Add a preview entry** in `packages/mail/scripts/previews.ts`
|
|
so the new template renders in `pnpm preview`.
|
|
|
|
## Brand theming
|
|
|
|
Templates accept a `brand: MailBrand` prop with the following fields:
|
|
|
|
| Field | Source | Notes |
|
|
| --- | --- | --- |
|
|
| `productName` | `@hivegrid/brand` `BrandTokens.productName` | Defaults to "HiveGrid". |
|
|
| `logoUrl` | `BrandTokens.assets.logoUrl` | Optional. Falls back to wordmark. |
|
|
| `primaryColor` | `BrandTokens.mail.colors.primary` | CTA background. |
|
|
| `primaryTextColor` | `BrandTokens.mail.colors.primaryText` | CTA foreground. |
|
|
| `tenantName` | derived from tenant `displayName` | Used in greeting/footer copy. |
|
|
| `supportEmail` / `supportFromName` | `BrandTokens.support.*` | Footer + sign-off. |
|
|
| `privacyUrl` / `termsUrl` / `imprintUrl` | `BrandTokens.legal.*` | DSGVO/CAN-SPAM compliance. |
|
|
|
|
`withBrandDefaults(override?)` merges a partial override into the
|
|
platform defaults — call it once per render so missing tenant fields
|
|
do not blank out the design.
|
|
|
|
## Plain-text fallback
|
|
|
|
`renderTransactionalEmail(template, props)` returns both `html` and a
|
|
plain-text `text` variant. The text is produced from the rendered
|
|
HTML by `htmlToPlainText` in `render-helpers.ts` — anchor URLs are
|
|
preserved as `label (url)` so text-mode clients keep functional
|
|
CTAs.
|
|
|
|
Mailjet forwards both parts in a MIME-multipart envelope; clients
|
|
choose which to display.
|
|
|
|
## Testing
|
|
|
|
- **Snapshot tests** are mandatory. Each template owns a
|
|
`__snapshots__/<TemplateName>.test.tsx.snap` capturing both the
|
|
HTML and the text output. Reviewers compare snapshot diffs against
|
|
the design intent.
|
|
- **XSS-safety tests** verify that React's default escaping turns
|
|
`<script>` into `<script>` for at least one user-supplied
|
|
prop per template.
|
|
- **URL-validation tests** verify that `javascript:`, `http://`,
|
|
`data:`, and malformed URLs are rejected when passed to `<Button>`.
|
|
- Run `pnpm --filter @hivegrid/mail test` to execute the suite.
|
|
|
|
## Live preview workflow
|
|
|
|
```
|
|
pnpm --filter @hivegrid/mail preview
|
|
```
|
|
|
|
Then open http://localhost:3001 — the index page lists every
|
|
template and links to the rendered HTML plus a `?format=text` link
|
|
for the plain-text fallback.
|
|
|
|
Sample props live in `packages/mail/scripts/previews.ts`. Update
|
|
them when adding a template; never commit real PII.
|
|
|
|
## Render pipeline
|
|
|
|
`renderTransactionalEmail(template, props)` from `@hivegrid/mail` is
|
|
the canonical entry point. The pre-Legacy-Provider-19 string-template renderer
|
|
(`renderTransactionalMailTemplate`) was retired in the legacy-cleanup
|
|
pass; the host application's wrapper at
|
|
`apps/web/app/modules/emails/utils/EmailTemplates.ts` adapts the
|
|
legacy template-name surface onto the React-Email pipeline.
|
|
|
|
| Legacy name | React template | Notes |
|
|
| --- | --- | --- |
|
|
| `welcome` | `welcome` | direct migration |
|
|
| `password-reset` | `password-reset` | direct migration |
|
|
| `user-invitation` | `invitation` | renamed for consistency |
|
|
| `email-verification` | `magic-link` | merged into magic-link flow (30-min expiry variant) |
|
|
| `account-setup` | `welcome` | unified onboarding (overridable subject/eyebrow/title/intro/actionLabel) |
|
|
| — | `magic-link` | new |
|
|
| — | `subscription-success` / `subscription-failed` | new (Legacy-Provider webhooks) |
|
|
| — | `invoice-sent` | new (Legacy-Provider invoices) |
|
|
| — | `tenant-notification` | new (in-app digest) |
|
|
|
|
## Security notes
|
|
|
|
- React's default escaping is the primary defense — manual
|
|
`escapeHtml` calls are no longer required and any new
|
|
template that performs string concatenation in HTML attributes
|
|
will be rejected in code review.
|
|
- `<Button>` enforces an allow-list of URL schemes
|
|
(`https:`, `mailto:`) to prevent magic-link phishing via
|
|
`javascript:` or `data:` URLs.
|
|
- `dangerouslySetInnerHTML` is forbidden in
|
|
`packages/mail/src/templates-react/`. If you need rich text,
|
|
build a structured prop shape and render it as JSX.
|
|
- Brand logo URLs come from `packages/brand` which enforces an
|
|
https-only allow-list; the React templates never load
|
|
arbitrary tenant-supplied URLs.
|