Делаем фронтенд-сборку для верстки HTML-писем на MJML / forpes.ru

Главная
Делаем фронтенд-сборку для верстки HTML-писем на MJML

Делаем фронтенд-сборку для верстки HTML-писем на MJML +6

15.08.2025 12:02

berdnikovdim 0 168 Источник

Меня зовут Дима. Я Frontend разработчик в компании fuse8. В одном из проектов мы столкнулись с необходимостью упростить процесс верстки и тестирования HTML-писем. В итоге решили вынести шаблоны в отдельный репозиторий и собирать их с помощью MJML.

В этой статье разберём два ключевых этапа: сначала создадим репозиторий для верстки писем, а затем настроим локальную тестовую отправку через SMTP.

Вот ссылка на репозиторий, где можно взять готовый шаблон, запустить его и проверить. А о том, из чего он состоит и как формируется, читайте ниже.

Зачем всё это?

На проекте мы активно используем HTML-письма. Изначально шаблоны располагались прямо в микросервисах бэкенда — разрозненно, с повторяющимися частями. Это создавало сложности при сопровождении и тестировании писем. Захотелось упростить процесс разработки, а главное — сделать верстку и проверку писем удобной.

А верстать письма, как известно, больно. Это как будто вы верстаете под Internet Explorer — если вы, конечно, помните, что это такое.

Первый шаг: выносим письма в отдельный репозиторий

Мы решили создать отдельный репозиторий, в котором будут храниться все шаблоны писем. Бэкенд сможет подтягивать их централизованно.

Следующий шаг — выбор инструментов для верстки и тестирования. Рассматривались:

MJML
Maizzle
Foundation HTML

Хотелось писать на более высокоуровневом языке, используя предустановленные компоненты. В Maizzle и Foundation HTML показалось, что придется писать больше кода на чистом HTML.

В итоге остановились на MJML — языке разметки для email-писем, который компилируется в полноценный HTML, адаптированный под специфику email-клиентов.

Что такое MJML и чем он удобен?

MJML – это язык, предназначенный для верстки HTML писем, который компилируется в обычный HTML. Это значит, что можно писать в абстрактном синтаксисе, который затем превратится в HTML-код с поддержкой разных почтовых клиентов. Это облегчает адаптацию под разные почтовые клиенты и даёт возможность использовать:

адаптивную верстку;
предустановленные компоненты;
переиспользование кода с помощью mj-include.

Здесь можно посмотреть, как код mjml превращается в html.

Базовая настройка проекта

Разберём базовую настройку проекта — без углубления в синтаксис MJML.

Установим зависимости:

npm install mjml live-server concurrently

Что делает каждая из них:

mjml — компиляция MJML → HTML
live-server — запуск dev-сервера с live reload (можно использовать любой сервер)
concurrently — параллельный запуск команд

Настройка package.json

Добавим в scripts:

"scripts": {

  "start": "mjml --watch ./src/templates/**/*.mjml --output ./templates",

  "server": "live-server --host=localhost --watch=templates --open=templates --ignorePattern=\".*.mjml\"",

  "dev": "concurrently \"npm run start\" \"npm run server\"",

  "build": "mjml ./src/templates/**/*.mjml --output ./templates"

}

Что делает каждая команда:

start — следит за файлами *.mjml в src/templates, компилирует в ./templates
server — поднимает сервер и отслеживает изменения в ./templates
dev — запускает start и server параллельно
build — однократная сборка шаблонов без вотчера

Создаём первый шаблон

Создадим файл example.mjml по пути /src/templates/example.mjml, в папке /src/templates будут все шаблоны. В файл добавим следующий код:

<mjml>

  <mj-body background-color="#f5f5f5">

    <mj-section padding="40px 0 20px">

      <mj-column>

        <mj-text align="center" font-size="28px" font-weight="bold">Письмо на mjml</mj-text>

      </mj-column>

    </mj-section>

    <mj-section background-color="#ffffff">

      <mj-column>

        <mj-image src="https://placehold.jp/300x200.png" />

      </mj-column>

      <mj-column>

        <mj-text font-size="18px" font-weight="bold">Привет, мир!</mj-text>

        <mj-text>Это письмо отправлено с помощью MJML.</mj-text>

      </mj-column>

    </mj-section>

    <mj-section>

      <mj-column>

        <mj-button href="#" background-color="#4CAF50">Подписаться</mj-button>

      </mj-column>

    </mj-section>

  </mj-body>

</mjml>

Запускаем npm run dev — и в браузере откроется HTML, сгенерированный из MJML. При каждом изменении шаблона страница будет автоматически обновляться. Также полезно создать папку ./src/parts для переиспользуемых частей верстки.

В результате получим десктопную и мобильную версии.

В папке ./src/parts создаём переиспользуемые части писем:

./src/parts/global-settings.mjml

<mj-style inline="inline">

  body { background-color: #f0f4f6; font-family: Arial, sans-serif; }

  a { color: #1d5cdb; text-decoration: none; }

</mj-style>

<mj-attributes>

  <mj-text

    font-size="17px"

    line-height="24px"

    color="#000"

    padding-top="5px"

    padding-bottom="5px"

  />

</mj-attributes>

./src/parts/header.mjml

<mj-section>

  <mj-column>

    <mj-image

      src="https://placehold.jp/82x47.png"

      alt="Логотип"

      width="82px"

      height="47px"

    />

  </mj-column>

</mj-section>

Подключим их в example.mjml и удалим лишние стили:

<mjml>

  <mj-head>

    <mj-include path="../parts/global-settings.mjml" />

    <mj-title>Пример</mj-title>

  </mj-head>

  <mj-body>

    <mj-include path="../parts/header.mjml" />

    <mj-section padding="40px 0 20px">

      <mj-column>

        <mj-text align="center" font-size="28px" font-weight="bold">Письмо на mjml</mj-text>

      </mj-column>

    </mj-section>

    <mj-section background-color="#ffffff">

      <mj-column>

        <mj-image src="https://placehold.jp/300x200.png" />

      </mj-column>

      <mj-column>

        <mj-text font-size="18px" font-weight="bold">Привет, мир!</mj-text>

        <mj-text>Это письмо отправлено с помощью MJML.</mj-text>

      </mj-column>

    </mj-section>

    <mj-section>

      <mj-column>

        <mj-button href="#" background-color="#4CAF50">Подписаться</mj-button>

      </mj-column>

    </mj-section>

  </mj-body>

</mjml>

Получаем результат:

В итоге:

Можем глобально задавать общие стили и настройки для компонентов с помощью global-settings.
Можем выносить по аналогии части кода, как это сделано в header.
Разрабатываем и видим изменения в браузере в реальном времени за счет настроенного dev сервера.

Использование шаблонов на бэкенде (Go)

У нас на проекте бэкенд написан на Go. Собранные шаблоны писем попадают в папку ./templates. Оттуда бэкенд может их подтягивать и отправлять письма. В нашем случае подключение шаблонов выглядит так:

В корне проекта — go.mod:

module gitlab.site.ru/front-html-email-templates

go 1.22.0

В ./templates/templates.go:

package templates

import _ "embed"

//go:embed example.html

var Example string

При добавлении нового шаблона нужно добавить аналогичную переменную в templates.go.

Также в письмах есть переменные, которые подставляет бэкенд с помощью своего шаблонизатора. В нашем случае для переменных следующий синтаксис {{.variableName}}

<mjml>

  <mj-body>

    <mj-section padding="40px 0 20px">

      <mj-column>

        <mj-text align="center" font-size="28px" font-weight="bold">{{.title}}</mj-text>

      </mj-column>

    </mj-section>

  </mj-body>

</mjml>

Чтобы понимать, какие переменные нужны в шаблоне, мы создали папку ./docs/templates, где хранятся md файлы с одноименным названием шаблона и описанием того, какие переменные используются, например:

## Candidate

Шаблон письма 'Отклик без вакансии'

### Переменные

- ``{{.date}}`` Дата отклика

- ``{{.title}}`` Название вакансии

- ``{{.region}}`` Регион

- ``{{.name}}`` ФИО

- ``{{.phone}}`` Телефон

- ``{{.email}}`` Email

- ``{{.comment}}`` Комментарий

- ``{{.resume_link}}`` Ссылка на резюме

- ``{{.year}}`` Актуальный год отправки письма

Сами переменные в файлы может занести бэкендер, а фронтендеру остается расставить их в верстке по правильным местам.

Локальное тестирование по smtp

Напишем простой js скрипт, который будет отправлять наши шаблоны на реальную почту.

Для начала установим следующие пакеты:

npm install dotenv nodemailer

dotenv — пакет для загрузки .env файлов в js;
nodemailer— пакет для отправки писем с поддержкой SMTP.

После этого создадим файл ./send-test-email.js и добавим код:

import nodemailer from 'nodemailer'

import dotenv from 'dotenv'

import fs from 'fs/promises'

dotenv.config()

async function sendTestEmail() {

	const transporter = nodemailer.createTransport({

		host: process.env.SMTP_HOST,

		port: process.env.SMTP_PORT,

		secure: true, // true для 465, false для других портов

		auth: {

			user: process.env.SEND_FROM_EMAIL,

			pass: process.env.SEND_FROM_EMAIL_PASSWORD,

		},

	})

	const htmlEmailString = await fs.readFile(

		./templates/${process.env.TEMPLATE_NAME}.html,

		'utf-8'

	)

	const mailOptions = {

		from: "Test Sender" <${process.env.SEND_FROM_EMAIL}>,

		to: process.env.SEND_TO_EMAIL,

		subject: 'Test HTML Email',

		html: htmlEmailString,

	}

	const info = await transporter.sendMail(mailOptions)

	console.log('Message sent: %s', info.messageId)

}

sendTestEmail().catch(console.error)

Это простая реализация отправки письма по SMTP. Также нам нужно создать .env файл с нужными переменными:

TEMPLATE_NAME=email-confirmation

SEND_TO_EMAIL=test@fuse8.online

SMTP_HOST=smtp.mail.ru

SMTP_PORT=465

SEND_FROM_EMAIL=test@mail.ru

SEND_FROM_EMAIL_PASSWORD=BcsftTdfdsf

TEMPLATE_NAME — название шаблона, который будет отправлен;
SEND_TO_EMAIL— куда будет отправлено письмо;
SMTP_HOST— smtp хост;
SMTP_PORT— порт;
SEND_FROM_EMAIL— откуда будет уходить письмо.
SEND_FROM_EMAIL_PASSWORD— пароль от отправляемой почты.

В основном меняются переменные TEMPLATE_NAME и SEND_TO_EMAIL. Для тестирования разных шаблонов и разных почтовых клиентов.

Остальные переменные нужно настроить один раз. Например, как подключиться по SMTP в mail почте https://help.mail.ru/mail/login/mailer.

После всей настройки для отправки письма нужно вызвать скрипт:

node ./send-test-email.js

Для удобства можно добавить скрипт в package.json, также можно сделать поддержку массовой отправки шаблона на разные почтовые клиенты.

Заключение

Текущую концепцию можно применить и с другими инструментами. В результате у нас есть:

централизованный репозиторий для html писем;
верстка писем с лучшими практиками и переиспользуемыми частями;
локальное тестирование по smtp.

Нужно иметь в виду, что верстка все равно может разваливаться в старых outlook клиентах и с такими решениями как MJML, где даются эталонные шаблоны писем. Даже использование лучших практик не избавляет от этой проблемы. Чтобы избежать «разваливания», для старых решений можно использовать максимально тривиальную верстку: простые тексты и заголовки, отсутствие стилизаций и визуальных элементов. Если вы знаете, как иначе можно выйти из ситуации, расскажите в комментариях – будет полезно ?