# newsletter-builder-react
> A free, open-source (MIT), provider-agnostic visual email newsletter builder for React. Drag-and-drop editor, email-safe table-based HTML compiler with inlined CSS, plain-text generator, merge tags, light/dark mode. It outputs `{ html, text, subject }` and never sends email itself, so there is no vendor lock-in.
## Install
```bash
npm install newsletter-builder-react
```
Peer dependencies: `react` and `react-dom` 18 or 19. Import the editor styles once:
```tsx
import 'newsletter-builder-react/styles.css'
```
The editor components are client components (`'use client'`). In Next.js App Router, render them from a client component or a file that starts with `'use client'`. The compiler functions are pure and run anywhere (server, edge, browser, Node scripts).
## Quick start
```tsx
'use client'
import { NewsletterBuilder, createWelcomeTemplate } from 'newsletter-builder-react'
import 'newsletter-builder-react/styles.css'
export default function Editor() {
return (
console.log(doc)}
/>
)
}
```
Compile on the server and hand the payload to any provider:
```ts
import { compileNewsletter } from 'newsletter-builder-react'
const { html, text, subject } = compileNewsletter(doc, {
variables: { firstName: 'Ada', unsubscribeUrl: 'https://example.com/u/123' },
})
// Pass { html, text, subject } to SMTP2GO, Bird, Mailchimp, HubSpot, ActiveCampaign, Nodemailer...
```
## Entry points
- `newsletter-builder-react` - components, hooks, compiler, types (safe for browser and server).
- `newsletter-builder-react/styles.css` - editor chrome styles.
- `newsletter-builder-react/node` - server only. Exports the development-only `sendDevEmail()`.
## Components
### ``
Complete editor: block palette, canvas, inspector, preview, HTML and plain-text views, undo/redo, quick-start walkthrough. It fills its parent, so give the parent a height.
Props:
- `initialDocument?: NewsletterDocument` - starting document. Read once on mount. Use `key` to remount.
- `onChange?: (document: NewsletterDocument) => void` - called after each committed edit.
- `variables?: Record` - runtime customer values, applied to the canvas, preview and exported HTML. Not editable in the UI. Change at any time to swap customer data.
- `previewData?: Record` - sample values for previews only (not exported). Defaults to `DEFAULT_PREVIEW_DATA`. Define outside the component or memoise.
- `onPreviewDataChange?: (data) => void` - called when sample values are edited in the Variables tab.
- `mergeTags?: MergeTagDefinition[]` - tags offered in menus. Defaults to `DEFAULT_MERGE_TAGS`.
- `onImageUpload?: (file: File) => Promise` - return a public https URL for an uploaded image. Without it uploads become data URLs (preview only).
- `onExport?: (email: CompiledEmail, action: 'copy-html' | 'copy-text' | 'download-html') => void`
- `showWalkthrough?: boolean` (default true), `onWalkthroughDismiss?: () => void`
- `defaultView?: 'edit' | 'preview' | 'html' | 'text'`, `defaultColorMode?: 'light' | 'dark'`
- `uiTheme?: 'light' | 'dark'` - colour theme of the editor chrome.
- `height?: number | string` (default `'100%'`), `className?: string`
### ``
Renders a document exactly as exported, inside a sandboxed iframe (`sandbox="allow-same-origin allow-popups"`, no scripts).
Props:
- `document: NewsletterDocument` (required)
- `variables?: Record` - always applied, wins over `previewData`
- `previewData?: Record` - sample values for this preview
- `colorMode?: 'light' | 'dark' | 'auto'` (default `'light'`)
- `device?: 'desktop' | 'mobile'` (default `'desktop'`; mobile is 375px wide)
- `autoHeight?: boolean` - size the frame to its content
- `title?: string`, `className?: string`, `style?: CSSProperties`
```tsx
```
### `useNewsletterEditor(initial, onChange?)`
Headless editor state (reducer with undo/redo) for building a custom UI. Returns `NewsletterEditorApi` with the current `document`, `selectedId`, `selectedBlock`, `canUndo`, `canRedo`, and actions `addBlock(block, location)`, `appendBlock(block)`, `moveBlock(id, location)`, `updateBlock(id, patch)`, `removeBlock(id)`, `duplicateBlock(id)`, `nudgeBlock(id, -1 | 1)`, `updateMeta({ subject, preheader })`, `updateTheme(patch)`, `replaceDocument(doc)`, `select(id)`, `undo()`, `redo()`.
## Document model
`NewsletterDocument` is plain JSON (serialisable, safe to store in a database):
```ts
interface NewsletterDocument {
version: 1
subject: string // merge tags allowed
preheader: string // inbox preview text
theme: NewsletterTheme
blocks: NewsletterBlock[]
}
```
Block types (discriminated by `type`): `header` (text, level 1-3, align, color?), `text` (sanitised inline `html`, align, fontSize), `image` (src, alt, widthPercent, align, href), `button` (label, href, align, fullWidth, borderRadius, backgroundColor?, textColor?), `divider` (thickness, style, widthPercent), `spacer` (height), `footer` (reason, companyName, address, unsubscribeLabel, unsubscribeUrl, showPreferences, preferencesLabel, preferencesUrl, align), and `columns` (2-4 cells, each with `widthPercent` and `blocks`; `gap`, `stackOnMobile`). `columns` can only live at the document root.
`NewsletterTheme`: `fontStack`, `headingFontStack` (ids from `FONT_STACKS`), `contentWidth` (480-720), `baseFontSize`, `containerRadius`, and two `ThemeColors` palettes, `light` and `dark` (`pageBackground`, `contentBackground`, `text`, `mutedText`, `heading`, `link`, `buttonBackground`, `buttonText`, `divider`).
Factories: `createBlankDocument()`, `createWelcomeTemplate()`, `createProductUpdateTemplate()`, `createBlock(type)`, `createColumns(2 | 3 | 4)`, `createTheme(overrides)`.
## Compiler
```ts
compileNewsletter(document: NewsletterDocument, options?: CompileOptions): CompiledEmail
```
`CompileOptions`: `variables`, `previewData` (merged under `variables`), `colorMode` (`'auto'` default, `'light'`, `'dark'`), `lang` (default `en`), `dir` (`ltr` | `rtl`).
`CompiledEmail`: `{ html: string; text: string; subject: string }`.
Output guarantees: nested `` layout, inlined CSS, no Flexbox/Grid/external stylesheets, `` and ``, a `@media (prefers-color-scheme: dark)` block (plus Outlook.com `[data-ogsc]`/`[data-ogsb]` selectors), a responsive `@media (max-width: px)` stacking rule, MSO conditional comments for Outlook, bulletproof buttons, hidden preheader, escaped merge-tag values, and sanitised URLs (only `http`, `https`, `mailto`, `tel`, and `data:image/*` for images).
Other helpers: `renderPlainText(doc)`, `richTextToPlain(html)`, `lintNewsletter(doc, html?)` returns `LintIssue[]` (empty subject or preheader, missing alt text, missing images, relative or data-URL image sources, buttons without links, missing unsubscribe link or postal address, Gmail 102 KB clipping), `applyMergeTags`, `extractMergeTags`, `escapeHtml`, `sanitizeRichText`, `sanitizeUrl`, tree helpers `findBlock`, `insertBlock`, `removeBlock`, `updateBlock`, `moveBlock`, `cloneBlock`, `createId`.
## Merge tags and variables
Write `{{name}}` anywhere: subject, preheader, headings, text, button labels and URLs, footer fields. Names match `[A-Za-z_][A-Za-z0-9_.-]*` and whitespace inside the braces is allowed (`{{ firstName }}`).
- At compile time, `variables` are substituted (HTML-escaped; URLs are sanitised after substitution).
- Tags with no value are left as-is, so a downstream engine (Mailchimp `*|FNAME|*` mapping, HubSpot, Handlebars, Liquid) can still resolve them.
- `previewData` is for previews only and is merged under `variables`.
```ts
compileNewsletter(doc, { variables: { firstName: 'Ada' } })
```
Per-recipient sending: compile once without variables to get a reusable template, then substitute per recipient with `applyMergeTags(html, values, { escapeValues: true })`.
## Theming and dark mode
Set colours in `document.theme.light` and `document.theme.dark`. Light colours are inlined on every element; dark colours are emitted only inside the dark media query, so clients that do not support dark mode always render light. Explicit per-block colour overrides (`header.color`, `button.backgroundColor`) are not swapped in dark mode. Font stacks are email-safe system stacks (`FONT_STACKS`): `system`, `helvetica`, `verdana`, `trebuchet`, `tahoma`, `georgia`, `palatino`, `times`, `courier`. Web fonts are intentionally not used because most clients ignore them.
## Provider integration
The package never talks to a provider. Pass the payload:
```ts
// Nodemailer / any SMTP (SMTP2GO, Bird, custom)
await transporter.sendMail({ from, to, subject, html, text })
// Mailchimp: create a campaign and PUT html to /campaigns/{id}/content { html }
// HubSpot: marketing email content or single-send API with the compiled html
// ActiveCampaign: create a message with html and text fields
```
Replace provider-specific unsubscribe tags by setting the footer `unsubscribeUrl` to the provider's merge syntax (for example `*|UNSUB|*` for Mailchimp, `%%unsubscribe_link%%` style tokens elsewhere). Unknown `{{tags}}` are preserved untouched.
## sendDevEmail (DEVELOPMENT ONLY)
```ts
import { sendDevEmail } from 'newsletter-builder-react/node'
await sendDevEmail({
from: 'Acme ',
to: 'ada@example.com',
email: compileNewsletter(doc),
smtp: { host: 'localhost', port: 1025, startTls: false }, // Mailpit / MailHog / Mailtrap
})
```
Uses only `node:net` and `node:tls`. Supports implicit TLS, STARTTLS and AUTH PLAIN. No queue, retries, pooling, DKIM signing or bounce handling.
**WARNING:** Do not use this for production sending. Without reverse DNS (PTR), SPF, DKIM and DMARC DNS TXT records, and server/IP warm-up, your messages will land in spam or be rejected. Use a transactional provider for production traffic.
## Deliverability checklist
- PTR (reverse DNS) record on the sending IP matches the HELO hostname.
- SPF TXT record authorises the sending servers.
- DKIM signing is enabled and the public key is published as a TXT record.
- DMARC TXT record at `_dmarc.yourdomain` (start with `p=none` and monitor).
- Warm up new IPs and domains gradually.
- Include a visible unsubscribe link and `List-Unsubscribe` / `List-Unsubscribe-Post` headers for bulk mail.
- Always send the `text` part alongside `html`.
- Keep HTML under 102 KB to avoid Gmail clipping.
## Accessibility and security notes
- The linter flags empty image alt text, missing unsubscribe links and Gmail clipping.
- Rich text is restricted to `b`, `strong`, `i`, `em`, `u`, `a`, `br` and sanitised on input and at compile time. `javascript:` and similar URLs are removed.
- The renderer iframe has no `allow-scripts`.
## Links
- License: MIT
- Docs: /docs
- Playground: /builder