For the revamp FxA emails project, we have an opportunity to modernize our email templates and evaluate what stack would be the most ideal.
This ADR is probably going to be a little beefy since it's going to capture not a single architectural decision, but several, and essentially become an outline for the Outreachy project. Some of these decisions can be pretty concisely written though; for example, we'd like to use Fluent for localization over GetText since we've moved other front-ends to use Fluent as it's preferred by the l10n team, and that can be captured in a sentence or two.
The ADR should cover:
What templating solution we ultimately want to use
Per the linked issue above, we talked about using EJS. Since fxa-settings, fxa-admin-panel, fxa-payments-server, and fxa-react (a shared package) are all using React components, we'd also like to consider using a stateless React solution that would export to static HTML, though maybe that's overkill. :grinning: We also want a quick pros/cons list of keeping the current solution, Mustache.
Let's consider MJML and maybe one other similar solution if there is another good option out there. Using MJML would be in tandem with the templating solution.
A chosen CSS solution
When emails are built by the server, we need the styles to be inserted inline since most email clients disregard <style> tags. However, inline styles aren't great for consistency across the look and feel of our emails and they make maintenance more difficult. We want to pick a solution that lets us use reusable classes during development but when built, can be turned into inline styles (if we don't use CSS modules, we will need to use a Webpack plugin, or another solution to do this for us). We currently use Tailwind in some of our other front-ends.
Email state previewing solution
It's notoriously difficult to preview what different email states look like in FxA for Engineering, Design, and Product. We've been using Storybook across other front-ends (all React-based, but there is an EJS option) to see what different state updates will do to a user interface and it's worked great for us, plus, we have automatic deployment already set up. Is there a better solution out there for previewing emails specifically, or is Storybook the most ideal, and can we somehow have a "preview in Mail client" button (which may call for using/researching into another library) since what's in Storybook won't be identical to previewing in a mail client?
Localization
While the templates are being reworked to use the new templating system, we want to use it as an opportunity to upgrade from GetText to Fluent.
Plaintext version approach
The plaintext version of emails is viewed when users prefer not to see rich HTML. They currently use handlebars syntax and partials, and are generated in the same fashion as the HTML templates (the template file is passed into the Handlebars renderer and localized). They also currently reside in the same directory as their HTML counterpart. We should investigate if we can automate a plaintext version from an HTML version or how to approach partials if we need them to render out text like they are now, and to see if we can import .txt files into Storybook (or whatever state previewing solution we choose). Depending on the decision here we may need a follow up issue in this epic.
Unit test plans
If we go with the React-based solution, it may make sense to use Jest to test the templates. However, we don't want a ton of time spent in test land. At the very least, we can take what we currently have and transfer/copy it, and look them over to see if anything can be improved without a high level of effort.
Integration and QA process
This includes mentioning how we plan to build out/hook these templates up with feature flags and mitigate risk. The fxa-auth-server already has some basic support for feature flagging, but FXA-3503 / #8600 should identify how we want to use these - do we want 3 different feature flags (one for each milestone of templates), do we want to flag individual templates, or should we have a single flag? There probably doesn't need to be a pros/cons section for this, but a section towards the top with a couple of paragraphs explaining the plans here.
--
We also want to be able to support rtl emails, see FXA-3388 / #8320. This may not need to be mentioned in the ADR but is something to keep in mind and plan for.
LZoog
commented
3 years ago
The ADR will close out this ticket as well as close FXA-1399 / https://github.com/mozilla/fxa/issues/4627.
For the revamp FxA emails project, we have an opportunity to modernize our email templates and evaluate what stack would be the most ideal.
This ADR is probably going to be a little beefy since it's going to capture not a single architectural decision, but several, and essentially become an outline for the Outreachy project. Some of these decisions can be pretty concisely written though; for example, we'd like to use Fluent for localization over GetText since we've moved other front-ends to use Fluent as it's preferred by the l10n team, and that can be captured in a sentence or two.
The ADR should cover:
What templating solution we ultimately want to use Per the linked issue above, we talked about using EJS. Since
fxa-settings,fxa-admin-panel,fxa-payments-server, andfxa-react(a shared package) are all using React components, we'd also like to consider using a stateless React solution that would export to static HTML, though maybe that's overkill. :grinning: We also want a quick pros/cons list of keeping the current solution, Mustache.Let's consider MJML and maybe one other similar solution if there is another good option out there. Using MJML would be in tandem with the templating solution.
A chosen CSS solution When emails are built by the server, we need the styles to be inserted inline since most email clients disregard
<style>tags. However, inline styles aren't great for consistency across the look and feel of our emails and they make maintenance more difficult. We want to pick a solution that lets us use reusable classes during development but when built, can be turned into inline styles (if we don't use CSS modules, we will need to use a Webpack plugin, or another solution to do this for us). We currently use Tailwind in some of our other front-ends.Email state previewing solution It's notoriously difficult to preview what different email states look like in FxA for Engineering, Design, and Product. We've been using Storybook across other front-ends (all React-based, but there is an EJS option) to see what different state updates will do to a user interface and it's worked great for us, plus, we have automatic deployment already set up. Is there a better solution out there for previewing emails specifically, or is Storybook the most ideal, and can we somehow have a "preview in Mail client" button (which may call for using/researching into another library) since what's in Storybook won't be identical to previewing in a mail client?
Localization While the templates are being reworked to use the new templating system, we want to use it as an opportunity to upgrade from GetText to Fluent.
Plaintext version approach The plaintext version of emails is viewed when users prefer not to see rich HTML. They currently use handlebars syntax and partials, and are generated in the same fashion as the HTML templates (the template file is passed into the Handlebars renderer and localized). They also currently reside in the same directory as their HTML counterpart. We should investigate if we can automate a plaintext version from an HTML version or how to approach partials if we need them to render out text like they are now, and to see if we can import .txt files into Storybook (or whatever state previewing solution we choose). Depending on the decision here we may need a follow up issue in this epic.
Unit test plans If we go with the React-based solution, it may make sense to use Jest to test the templates. However, we don't want a ton of time spent in test land. At the very least, we can take what we currently have and transfer/copy it, and look them over to see if anything can be improved without a high level of effort.
Integration and QA process This includes mentioning how we plan to build out/hook these templates up with feature flags and mitigate risk. The
fxa-auth-serveralready has some basic support for feature flagging, but FXA-3503 / #8600 should identify how we want to use these - do we want 3 different feature flags (one for each milestone of templates), do we want to flag individual templates, or should we have a single flag? There probably doesn't need to be a pros/cons section for this, but a section towards the top with a couple of paragraphs explaining the plans here.--
We also want to be able to support rtl emails, see FXA-3388 / #8320. This may not need to be mentioned in the ADR but is something to keep in mind and plan for.
┆Issue is synchronized with this Jira Task