Add email docs and `stacks-email` package by abovedave · Pull Request #2292 · StackExchange/Stacks

abovedave · 2026-06-01T12:53:25Z

Introduces @stackoverflow/stacks-email, a new (experimental) MJML powered email package for building, previewing, documenting, and compiling Stack Overflow email templates.

A reusable email component library
A template gallery for complete email examples
A shared MJML compile pipeline
Target-specific token replacement for preview, .NET/Razor, and Braze
A flexible Node/TypeScript package API
A narrower SvelteKit HTTP compile endpoint for service integration
Static compiled artifacts for use in stacks-docs

Background

Historically, Stack Overflow's email design system lived across several separate implementations, including the monolith and external marketing tools. Since 2020, the system has had limited modernization or maintenance.

This work is part of the 2026 rebrand rollout. The goal is to create a shared source of truth for email design patterns, implementation, previewing, and downstream consumption.

We selected MJML because it is widely adopted, MIT licensed, and abstracts much of the client-specific complexity of writing production email HTML.

Overview

Components

~/packages/stacks-email/components

Adds reusable email building blocks such as Button, Header, Footer, Card etc. Each defines their variants, options, tokens, and MJML render output in one place.

Templates

~/packages/stacks-email/templates

Adds example and reusable template definitions including Transactional, Newsletter, Promotional. These compose components into full MJML documents and can expose variants and props.

Compile APIs

The package can be consumed in several ways:

As a local/gallery app for previewing emails (this branch is currently live on email.stackoverflow.com)
As a Node/TypeScript library via @stackoverflow/stacks-email
As a deployed SvelteKit endpoint via POST /api/compile
As static compiled artifacts for docs previews
As raw MJML or compiled HTML output

The package API and HTTP API intentionally serve different use cases.

The package API is the full in-process integration surface for trusted TypeScript consumers. It supports catalog discovery, component compilation, template compilation, renderable dispatch, and lower-level MJML compilation primitives.

The HTTP endpoint is a narrower service integration surface. It currently focuses on composing transactional emails from a validated JSON block list, then returning compiled MJML and HTML. This keeps the cross-service contract small while still enabling non-TypeScript consumers to generate branded email output without embedding the package.

Documentation

Adds a new Email section to stacks-docs, including:

Email overview
Template documentation
Component documentation
Embedded email previews
MJML/HTML output tabs
Usage examples
Generated options tables

Usage

As a package

import {
    getEmailCatalog,
    compileEmailTemplate,
    compileEmailComponent,
    compileEmailRenderable,
} from "@stackoverflow/stacks-email";

const email = compileEmailTemplate({
    slug: "transactional",
    target: "braze",
    props: {
        headlineText: "Reset your password",
        ctaText: "Reset password",
    },
});

console.log(email.html);

As an endpoint

curl -X POST https://email.stackoverflow.design/api/compile \
  -H "Content-Type: application/json" \
  --data '{
    "template": "transactional",
    "target": "preview",
    "previewText": "Reset your password",
    "blocks": [
      {
        "type": "headline",
        "props": {
          "textContent": "Reset your password"
        }
      },
      {
        "type": "text",
        "props": {
          "textContent": "Click below to continue."
        }
      },
      {
        "type": "button",
        "props": {
          "href": "[[BUTTON_URL]]",
          "text": "Reset password"
        }
      }
    ]
  }'

As static docs artifacts

@stackoverflow/stacks-email/sveltekit exports route handlers used by stacks-docs to serve precompiled email HTML, MJML, and manifest data.

Compile targets

Every compile supports a target:

preview: replaces tokens with sample values
dotnet: replaces tokens with Razor model bindings
braze: replaces tokens with Braze/Liquid-style values

This allows the same email source to produce output for different downstream systems.

Notes for reviewers

Suggested review path:

Start with packages/stacks-email/README.md
Review the component structure in packages/stacks-email/components
Review template composition in packages/stacks-email/templates
Review the compile pipeline in packages/stacks-email/src/lib/pipeline
Review public API exports in packages/stacks-email/src/lib/api
Review the HTTP endpoint in packages/stacks-email/src/routes/api/compile/+server.ts
Review docs integration in packages/stacks-docs/src/components/StacksEmailEmbed.svelte
Review static artifact handlers under packages/stacks-docs/src/routes/email/compiled

Current limitations / Follow-ups

This is mostly experimental but wanted to at least get the design elements and static markup available for consumption.
Open to ideas for a testing strategy for a follow-up PR.
The endpoint is intentionally narrower than the package API.
The package compiles email markup; it does not send emails.
Real inbox/client testing is still required before using output in production sends (Litmus?).
Additional templates, variants, and target mappings can be added as rollout needs become clearer.
Production hosting and ownership model should be finalized separately from this package implementation (hi platform team!)
Add Figma Code Connect
Sync with tools e.g., Braze API

changeset-bot · 2026-06-01T12:53:29Z

⚠️ No Changeset found

Latest commit: 2cb9276

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

netlify · 2026-06-01T12:53:34Z

✅ Deploy Preview for stacks ready!

Name	Link
🔨 Latest commit	`2cb9276`
🔍 Latest deploy log	https://app.netlify.com/projects/stacks/deploys/6a4d5e57a00ef00008e67d04
😎 Deploy Preview	https://deploy-preview-2292--stacks.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-06-12T09:48:47Z

✅ Deploy Preview for stackoverflow-email ready!

Name	Link
🔨 Latest commit	`2cb9276`
🔍 Latest deploy log	https://app.netlify.com/projects/stackoverflow-email/deploys/6a4d5e579f596a00087f1e7e
😎 Deploy Preview	https://deploy-preview-2292--stackoverflow-email.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

…mail # Conflicts: # package-lock.json

dancormier

Really nice work here @abovedave. Adding stacks-email seems reasonable and I think this is looking pretty solid. I noticed a few bugs that I think shouldn't be too tough to handle

Note

I noticed a bunch of whitespace-only changes to a couple of yaml files and undid just the whitespace changes to reduce the noise.

dancormier · 2026-07-07T18:21:23Z

+
+  <Notice variant="info" class="s-anchors s-anchors__inherit s-anchors__underlined mt32">
+      <p class="mb0">Looking for the previous version of Stacks? <a href="https://v2.stackoverflow.design/product/develop/using-stacks/">Go to the classic v2 documentation</a>.</p>
+  </Notice>


Looks much nicer this way

dancormier · 2026-07-07T18:25:03Z

 .ff-stack-sans-headline,
 .ff-stack-sans-headline-notch {
-    font-family: "Stack Sans Headline";
+    font-family: "Stack Sans Headline" !important;


Was the heading font being overridden by something? I'm not necessarily against adding !important here but just curious about the issue.

dancormier · 2026-07-07T18:46:02Z

+        tokens: {
+            FIRST_NAME: "@Model.FirstName",
+            BUTTON_LABEL: "@Model.ButtonLabel",
+            BUTTON_URL: "@Model.ButtonText",


Should BUTTON_URL use @Model.ButtonText? Seems like @Model.ButtonText would be the expected text content of the button.

dancormier · 2026-07-07T18:52:03Z

+
+        <Select
+            id={`email-target-${kind}-${slug}`}
+            label={null}


Nit: this select should have an accessible name

dancormier · 2026-07-07T19:42:46Z

+        defineOption({
+            name: "logoSrc",
+            type: "string",
+            initialValue: "/email/stack-overflow-logo.png",


The README describes email.html as “ready-to-send HTML”, but the default image sources are root-relative /email/… URLs. These images would likely break once sent outside the preview host.

Should we make asset URLs absolute/configurable or clarify that consumers must rewrite/package image assets before sending?

dancormier · 2026-07-07T20:13:46Z

+                        Section(
+                            [
+                                Button("primary", {
+                                    href: "[[CTA_URL]]",


[[CTA_URL]] doesn’t appear in the compile target token maps, so this href will remain literal in preview/.NET/Braze output. Can we either use the existing [[BUTTON_URL]] token here or add CTA_URL replacements for every target in src/lib/tokens.ts?

dancormier · 2026-07-07T20:23:10Z

+          - title: "Email gallery"
+            slug: "emails"
+            externalUrl: https://email.stackoverflow.design
+


Looks like we could use an image here

Add email docs and stacks-email templates

dfc6659

abovedave added docs Issues with the documentation site email issues with email templates and documentation labels Jun 1, 2026

github-advanced-security AI found potential problems Jun 1, 2026

View reviewed changes

Comment thread packages/stacks-email/src/lib/pipeline/compile.ts Fixed

Comment thread packages/stacks-email/src/lib/pipeline/compile.ts Fixed

abovedave added 24 commits June 2, 2026 18:41

refactor(stacks-email): modernize email engine

97dad67

feat(stacks-docs): serve static email previews

b58f3d3

docs(email): update email docs for static previews

8220ccc

run format

ecb53cd

docs

3d07817

fix(stacks-email): resolve json2mjml in dev SSR

ce82f95

readme

df08b3c

fix CJS module import

5a42996

move fonts to tokens

3416529

nicer loading style for embed

9eef0c0

simplify head injection

a7dc768

fix linting errors

23b55f1

refactor to avoid the round trips with string vs json object mjml

7bd9258

remove duplicate code between email and component variants

8289b65

remove duplicated markdown render

a939f0e

tidy

aa0d3a3

add strip graphic variant

df9ea6c

remove divider placeholder

133f545

no need for explicity default

4565a76

add card

9a435bc

text node adjust

1d0ff88

link card with arrow variant

e8f41b8

callout component

4cf2c1a

callout and subtitle

0ac4249

abovedave added 7 commits June 3, 2026 18:19

fix color name

75bbc49

remove unused

2335fa0

newsletter

09d4fdf

add promo style

eb23303

tweaks to inbox preview

a6794dd

dev survey email

d07bdeb

prebuild

7324617

abovedave added 10 commits June 23, 2026 15:55

Merge branch 'main' of https://github.com/StackExchange/Stacks into e…

d7b3e97

…mail # Conflicts: # package-lock.json

add email version

6629451

experimental notice

b9a5443

allow any template for the endpoint

20bb041

Merge branch 'main' of https://github.com/StackExchange/Stacks into e…

a84c858

…mail # Conflicts: # package-lock.json

new homepage from community-guidelines branch

178f445

add a title tag

2c1029d

npm run format

18a3484

rebuild with newer vesion of npm

96078c5

tidy unused

ee4744e

abovedave marked this pull request as ready for review June 26, 2026 12:18

abovedave requested a review from a team as a code owner June 26, 2026 12:19

dancormier added 2 commits July 7, 2026 14:22

style(docs): restore color yaml formatting

f0a9656

style(docs): restore structure yaml formatting

2cb9276

dancormier requested changes Jul 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add email docs and `stacks-email` package#2292

Add email docs and `stacks-email` package#2292
abovedave wants to merge 44 commits into
mainfrom
email

abovedave commented Jun 1, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

netlify Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

dancormier left a comment

Uh oh!

dancormier Jul 7, 2026

Uh oh!

dancormier Jul 7, 2026

Uh oh!

dancormier Jul 7, 2026

Uh oh!

dancormier Jul 7, 2026

Uh oh!

dancormier Jul 7, 2026

Uh oh!

dancormier Jul 7, 2026

Uh oh!

dancormier Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

abovedave commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Overview

Components

Templates

Compile APIs

Documentation

Usage

As a package

As an endpoint

As static docs artifacts

Compile targets

Notes for reviewers

Current limitations / Follow-ups

Uh oh!

changeset-bot Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

netlify Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for stacks ready!

Uh oh!

Uh oh!

Uh oh!

netlify Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for stackoverflow-email ready!

Uh oh!

dancormier left a comment

Choose a reason for hiding this comment

Uh oh!

dancormier Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dancormier Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dancormier Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dancormier Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dancormier Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dancormier Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

dancormier Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

abovedave commented Jun 1, 2026 •

edited

Loading

changeset-bot Bot commented Jun 1, 2026 •

edited

Loading

netlify Bot commented Jun 1, 2026 •

edited

Loading

netlify Bot commented Jun 12, 2026 •

edited

Loading