[PM-26551] MJML build script #6417

ike-kottlowski · 2025-10-06T16:53:52Z

🎟️ Tracking

📔 Objective

There is no general build support for MJML templates currently. The changes here are meant to give developers the tools needed to generate *.html.hbs files using MJML templating.

The build script supports compiling MJML templates to:

.html: npm run build
.html.hbs: npm run build:hbs
minified .html.hbs: npm run build:minify

A watch feature is included which compiles the MJML template to HTML, as well as a prettier feature.

# watch for file changes and recompile as needed
npm run watch

# apply prettier formatting
npm run prettier

⏰ Reminders before review

Contributor guidelines followed
All formatters and local linters executed and passed
Written new unit and / or integration tests where applicable
Protected functional changes with optionality (feature flags)
Used internationalization (i18n) for all UI strings
CI builds passed
Communicated to DevOps any deployment requirements
Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

👍 (:+1:) or similar for great changes
📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
❓ (:question:) for questions
🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
🎨 (:art:) for suggestions / improvements
❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
⛏ (:pick:) for minor or nitpick changes

(cherry picked from commit 24783ee)

github-actions · 2025-10-06T17:05:55Z

Checkmarx One – Scan Summary & Details – 27208446-5d4a-4317-aa03-a1fae73bdd0b

New Issues (2)

Checkmarx found the following issues in this Pull Request

Severity	Issue	Source File / Package	Checkmarx Insight
	CSRF	/src/Api/Vault/Controllers/CiphersController.cs: 1511	details Method at line 1511 of /src/Api/Vault/Controllers/CiphersController.cs gets a parameter from a user request from id. This parameter value flows ... `ID: pN371p7oxzg66CFSL1H%2F7897Dng%3D` Attack Vector
	CSRF	/src/Api/Vault/Controllers/CiphersController.cs: 1392	details Method at line 1392 of /src/Api/Vault/Controllers/CiphersController.cs gets a parameter from a user request from id. This parameter value flows ... `ID: xow1RlTy2gYME4GMTq55sfh%2BBY0%3D` Attack Vector

Fixed Issues (1)

Great job! The following issues were fixed in this Pull Request

Severity	Issue	Source File / Package
	~~CSRF~~	/src/Api/Vault/Controllers/CiphersController.cs: 299

codecov · 2025-10-06T17:16:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 50.55%. Comparing base (fe32e88) to head (d50eb5d).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6417   +/-   ##
=======================================
  Coverage   50.55%   50.55%           
=======================================
  Files        1853     1853           
  Lines       82144    82144           
  Branches     7254     7254           
=======================================
  Hits        41525    41525           
  Misses      39036    39036           
  Partials     1583     1583

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

… formatting

trmartin4

This is so helpful, thank you! I've made a few suggestions.

trmartin4 · 2025-10-09T12:31:30Z

src/Core/MailTemplates/README.md

+These are the compiled HTML email templates that serve as the foundation for all HTML emails sent by the Bitwarden platform. They are generated from MJML source files and enhanced with Handlebars templating capabilities.
+
+### Generation Process
+- **Source**: Built from `*.mjml` files in the `./mjml` directory using the MJML build pipeline


Suggested change

- **Source**: Built from `*.mjml` files in the `./mjml` directory using the MJML build pipeline

- **Source**: Built from `*.mjml` files in the `./mjml` directory using the MJML build pipeline by the developer as they construct the email

trmartin4 · 2025-10-09T12:32:19Z

src/Core/MailTemplates/README.md

+
+### Generation Process
+- **Source**: Built from `*.mjml` files in the `./mjml` directory using the MJML build pipeline
+- **Build Tool**: Generated via PowerShell build script (`build.ps1`) or npm scripts


We should clarify what npm scripts we're referring to here.

And link to any of them we can.

trmartin4 · 2025-10-09T12:34:26Z

src/Core/MailTemplates/Mjml/README.md

+# MJML email templating

-This directory contains MJML templates for emails sent by the application. MJML is a markup language designed to reduce the pain of coding responsive email templates.
+This directory contains MJML templates for emails. MJML is a markup language designed to reduce the pain of coding responsive email templates. There are DRY features within the library which will improve code quality.


I'd suggest that we clarify what DRY is instead of using the acronym. Perhaps "The library allows us to introduce reusable components that reduce repeated code"?

trmartin4 · 2025-10-09T12:34:54Z

src/Core/MailTemplates/Mjml/README.md

-```bash
+## Implementation considerations
+
+These `MJML` templates are compiled into HTML which will then be further consumed by our HandleBars mail service. We can continue to use this service to assign values from our View Models. This leverages the existing infrastructure. It also means we can continue to use the double brace (`{{}}`) syntax within MJML since Handlebars can be used to assign values to those `{{variables}}`.


Suggested change

These `MJML` templates are compiled into HTML which will then be further consumed by our HandleBars mail service. We can continue to use this service to assign values from our View Models. This leverages the existing infrastructure. It also means we can continue to use the double brace (`{{}}`) syntax within MJML since Handlebars can be used to assign values to those `{{variables}}`.

These `MJML` templates are compiled into HTML which will then be further consumed by our Handlebars mail service. We can continue to use this service to assign values from our View Models. This leverages the existing infrastructure. It also means we can continue to use the double brace (`{{}}`) syntax within MJML since Handlebars can be used to assign values to those `{{variables}}`.

trmartin4 · 2025-10-09T12:35:37Z

src/Core/MailTemplates/Mjml/README.md

+
+Not all MJML tags have the same attributes, it is highly recommended to review the documentation on the official MJML website to understand the usages of each of the tags.
+
+### Possible process


Suggested change

### Possible process

### Recommended development process

Added information about build script definitions for MJML.

willmartian

What is the goal of this PR? It looks like it is more than just Windows compat, because the previous build script was 2 lines and the new one is >100? Could you update the PR description?

src/Core/MailTemplates/Mjml/README.md

jrmccannon

This is good from my perspective. We can revisit build and tooling optimizations later.

trmartin4

Thank you for all of your work on this!

willmartian

If you have availability and the timeline to merge this is flexible enough, I would appreciate it if you take a pass at making this more maintainable for UIF with my following suggestions. However, I also recognize that this script is fairly simple, so I am not going to block it going in if it needs to.

Use Typescript via Node's built in type stripping
Use ESM imports
Use a lightweight CLI builder like https://github.com/unjs/citty
Tests

(I would recommend asking an LLM to help with this!)

* docs: update readme for MJML * docs: add readme for MailTemplates directory * feat: add node build script for cross platform build support

ike-kottlowski added 2 commits October 6, 2025 12:14

feat: powershell build script

0085ff9

(cherry picked from commit 24783ee)

feat: update package.json

0805cce

ike-kottlowski requested review from a team and dani-garcia October 6, 2025 16:53

fix: prettier version

1be934d

ike-kottlowski marked this pull request as ready for review October 6, 2025 17:05

ike-kottlowski requested a review from a team as a code owner October 6, 2025 17:05

ike-kottlowski requested a review from willmartian October 6, 2025 17:05

ike-kottlowski added 4 commits October 6, 2025 16:16

feat: add watch functionality to have parity with build.sh

a016e6f

feat: add watch and hbs output to build script

57a007d

docs: update readme for MJML

57b2fe3

docs: styling and clarity

b9a57ab

ike-kottlowski requested review from vleague2 and removed request for willmartian October 7, 2025 19:46

ike-kottlowski added 2 commits October 7, 2025 17:21

docs: adding docs for email templates

a6d8984

docs: update based on feedback

f44e71a

vleague2 previously approved these changes Oct 8, 2025

View reviewed changes

ike-kottlowski marked this pull request as draft October 8, 2025 18:54

feat: change powershell to node build script for cross platform; also…

7828a08

… formatting

ike-kottlowski dismissed vleague2’s stale review via 7828a08 October 8, 2025 22:43

ike-kottlowski marked this pull request as ready for review October 8, 2025 22:47

Merge branch 'main' into auth/pm-26551/mjml-build-script

115ca4b

ike-kottlowski requested a review from jrmccannon October 8, 2025 22:47

trmartin4 requested changes Oct 9, 2025

View reviewed changes

ike-kottlowski and others added 2 commits October 9, 2025 09:24

docs: updated based on feedback

33251e0

Update README with build script details

d50eb5d

Added information about build script definitions for MJML.

willmartian requested changes Oct 9, 2025

View reviewed changes

jrmccannon requested changes Oct 9, 2025

View reviewed changes

src/Core/MailTemplates/Mjml/README.md Show resolved Hide resolved

ike-kottlowski mentioned this pull request Oct 9, 2025

[PM-25240] Send Access OTP email in MJML format #6411

Open

jrmccannon approved these changes Oct 9, 2025

View reviewed changes

ike-kottlowski requested review from trmartin4 and willmartian and removed request for dani-garcia October 9, 2025 18:54

trmartin4 approved these changes Oct 10, 2025

View reviewed changes

willmartian approved these changes Oct 10, 2025

View reviewed changes

ike-kottlowski merged commit d722314 into main Oct 10, 2025
40 checks passed

ike-kottlowski deleted the auth/pm-26551/mjml-build-script branch October 10, 2025 16:15

aliwahhan added a commit to aliwahhan/server that referenced this pull request Oct 12, 2025

[PM-26551] MJML build script (bitwarden#6417)

6abf905

* docs: update readme for MJML * docs: add readme for MailTemplates directory * feat: add node build script for cross platform build support

	- Source: Built from `*.mjml` files in the `./mjml` directory using the MJML build pipeline
	- Source: Built from `*.mjml` files in the `./mjml` directory using the MJML build pipeline by the developer as they construct the email

	These `MJML` templates are compiled into HTML which will then be further consumed by our HandleBars mail service. We can continue to use this service to assign values from our View Models. This leverages the existing infrastructure. It also means we can continue to use the double brace (`{{}}`) syntax within MJML since Handlebars can be used to assign values to those `{{variables}}`.
	These `MJML` templates are compiled into HTML which will then be further consumed by our Handlebars mail service. We can continue to use this service to assign values from our View Models. This leverages the existing infrastructure. It also means we can continue to use the double brace (`{{}}`) syntax within MJML since Handlebars can be used to assign values to those `{{variables}}`.


		Not all MJML tags have the same attributes, it is highly recommended to review the documentation on the official MJML website to understand the usages of each of the tags.

		### Possible process

[PM-26551] MJML build script #6417

[PM-26551] MJML build script #6417

Uh oh!

Conversation

ike-kottlowski commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎟️ Tracking

📔 Objective

⏰ Reminders before review

🦮 Reviewer guidelines

Uh oh!

github-actions bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

trmartin4 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

willmartian left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrmccannon left a comment

Choose a reason for hiding this comment

Uh oh!

trmartin4 left a comment

Choose a reason for hiding this comment

Uh oh!

willmartian left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ike-kottlowski commented Oct 6, 2025 •

edited

Loading

github-actions bot commented Oct 6, 2025 •

edited

Loading

codecov bot commented Oct 6, 2025 •

edited

Loading

willmartian left a comment •

edited

Loading