RFC: Expand the MJML migration guide with component mapping, validation guardrails, and agent-ready context

[mikeflame]

Summary

I'd like to rewrite Migrating to React Email (apps/docs/getting-started/migrating-to-react-email.mdx) from its current four-step outline into a complete migration playbook for teams with large MJML template catalogues: a full component mapping, the known hard parts with recipes, a validation methodology for verifying before/after render parity, and a structured checklist that AI coding agents can execute template-by-template. Docs-only change; no new packages or components required. I'm offering to write the whole thing as a PR if the scope below sounds right.

Motivation

I've been the target reader of this page three times. In late 2022 my team chose MJML over the then-weeks-old react-email for a production transactional email system. In 2024, at roughly 10x the sending volume and with marketing funnels added on top, we tried to migrate to react-email and gave up twice: once on the cost of converting a large MJML estate with no detailed guidance, and once on uncertainty about rendering for a slice of our audience that lives on very old Outlook and webmail clients. Both walls were documentation and validation gaps, not framework gaps.

The current guide is four bullet points. Meanwhile:

• The need is as old as the project (issue Document how to migrate from MJML to React Email #43 asked for exactly this) and the hardest parts have their own long threads (responsive columns in Responsive column #462, media queries in Media queries do not show up in browsers email clients #1095).
• The guide once had an "Automated" section pointing to a third-party migration service; it was removed in chore(docs): Remove automated section on MJML migration #1775 when that service went away, and nothing replaced it. Teams with hundreds of templates currently get no answer to "how do we do this safely at scale".
• The docs already ship llms.txt, so agent-consumable documentation is an established direction here. Migration is the ideal workload for it: repetitive, per-template, and mechanically verifiable.

Proposed scope

One expanded page (or a small set of sub-pages, maintainers' preference):

1. Component mapping table. Every common mj-* component mapped to its react-email equivalent (mj-section/mj-column → Section/Row/Column, mj-text → Text, mj-image → Img, mj-button → Button, mj-divider → Hr, mj-spacer → spacing patterns, mj-font → Font, mj-raw → JSX, and so on), including honest rows for components with no direct equivalent (mj-hero, mj-carousel, mj-accordion) with the recommended pattern for each.

2. Translation traps. The places where a mechanical 1:1 swap silently changes rendering: MJML's padding attribute model vs style props, mj-attributes/mj-all global defaults (recommended target: shared wrapper components), mj-style and css-class vs inline styles/Tailwind, mj-include vs component composition.

3. The hard parts, with recipes. Responsive column stacking (MJML stacks columns on mobile by default; react-email needs explicit media queries), MSO conditional comments for Word-engine Outlook, background images via VML. These are the top reasons migrations stall, and they map to the most-commented historical issues.

4. Validation guardrails. A methodology section for migrating at scale without regressions: render the MJML and react-email versions of each template to HTML, screenshot both across a representative client matrix (including legacy Outlook), and pixel-diff them, so the diff becomes the per-template acceptance gate for an incremental migration. I run exactly this kind of render-regression harness in production for our MJML catalogue today; the section would document the approach in tool-neutral terms (any screenshot/diff stack works), with pointers to the built-in Compatibility Checker for the client-support half of the question.

5. Agent context. A deterministic per-template checklist (convert → map components → apply trap rules → run validation → compare against threshold → escalate to a human on mismatch) written so a coding agent can execute it directly, with the validation loop from section 4 as its success criterion. This replaces the removed third-party "Automated" section with a first-party, vendor-neutral answer.

Out of scope (possible follow-ups)

• An actual codemod/CLI for MJML conversion.
• A packaged render-diff tool. The guide documents the methodology; tooling can come later if there's appetite.

Open questions for maintainers

1. Single long page vs migrating-to-react-email/ sub-pages?
2. Should the agent checklist live in the page itself, in llms.txt, or both?
3. Policy on mentioning community packages (e.g. MSO-conditional helpers): given chore(docs): Remove automated section on MJML migration #1775 removed a stale vendor link, I'd default to documenting the raw technique and avoiding third-party links unless you prefer otherwise.
4. Would you want the validation section to reference specific screenshot/testing services, or stay fully tool-neutral?

If this direction works for you, I'll open a PR against canary following the writing-docs workflow, structured so each section can be reviewed (or cut) independently.