Owlat Docs

ADR-001: Eigener E-Mail-Renderer statt MJML

Warum Owlat einen eigenen tabellenbasierten HTML-E-Mail-Renderer gebaut hat, statt MJML zu verwenden, und damit volle Kontrolle über VML, Dark Mode und clientspezifisches Rendering gewinnt.

  • Status: Angenommen
  • Datum: 2024-06-15

Kontext

Owlat muss eine JSON-Blockstruktur in responsive HTML-E-Mails überführen, die in allen großen E-Mail-Clients (Gmail, Outlook, Apple Mail, Yahoo) korrekt dargestellt werden. MJML ist der Industriestandard dafür und stellt eine Auszeichnungssprache bereit, die zu E-Mail-sicherem HTML kompiliert.

MJML hat für unseren Anwendungsfall allerdings Grenzen:

  • Keine feingranulare Kontrolle — MJML abstrahiert das zugrunde liegende tabellenbasierte HTML weg und erschwert damit fortgeschrittene Funktionen wie VML-Hintergründe, bedingte Inhalte oder clientspezifisches Rendering.
  • Bundle-Größe — MJML ist eine große Abhängigkeit (~2 MB), die das Serverless-Backend aufblähen würde.
  • Nicht passendes Blockmodell — Unser Editor verwendet ein JSON-Blockmodell (ähnlich Notion/Editor.js). Blöcke in MJML-Markup zu konvertieren, nur damit MJML daraus HTML macht, fügt eine unnötige Übersetzungsschicht hinzu.
  • Erweiterbarkeit — Eigene Blocktypen in MJML zu ergänzen erfordert MJML-Komponenten, die dessen interner API entsprechen; diese ist schlecht dokumentiert und eng an die Rendering-Pipeline gekoppelt.

Entscheidung

Einen eigenen tabellenbasierten HTML-E-Mail-Renderer (@owlat/email-renderer) bauen, der unser JSON-Blockformat direkt in E-Mail-sicheres HTML überführt.

Konsequenzen

Ermöglicht:

  • Direkte Kontrolle über jedes HTML-Attribut und damit VML-Unterstützung für Outlook (bulletproof Buttons, Hintergrundbilder, Verläufe)
  • Render-Simulation pro Client (Option targetClient) für treffsichere Vorschauen
  • Eigene Block-Registry für Blocktypen von Drittanbietern
  • CSS-Inlining mit selektiven Annotationen (@inline / @head-only)
  • Dark-Mode-Unterstützung mit Overrides pro Block
  • AMP-E-Mail-Ausgabe als erstklassiges Format
  • Analyse der E-Mail-Größe und Kompatibilitäts-Scoring
  • Kleineres Bundle — der Renderer wiegt ~50 KB gegenüber MJMLs ~2 MB

Trade-offs:

  • Wir tragen die volle Komplexität der Eigenheiten von E-Mail-Clients (Outlook-Conditional-Comments, CSS-Stripping in Gmail, Abstandsfehler bei Yahoo)
  • Neue Teammitglieder können sich nicht auf die MJML-Dokumentation stützen — sie müssen die API unseres Renderers lernen
  • Wir müssen eigene Kompatibilitätsdaten pflegen, statt uns auf die erprobte Ausgabe von MJML zu verlassen
WeiterADR-002: Convex als Backend