Эффективная разработка и отправка HTML-писем с помощью Maizzle 5 и Laravel 11

1. Зачем совмещать Maizzle 5 и Laravel 11?

• Maizzle упрощает верстку email-шаблонов, используя Tailwind CSS и «инлайнинг» стилей, оптимизацию HTML и удобные конструкции (layouts, partials, условия, циклы).
• Laravel предоставляет гибкую систему отправки писем (Mailables, Notifications, Queues) и всю бизнес-логику.
• При интеграции вы можете легко генерировать кросспочтово совместимые шаблоны и распределять их с помощью Laravel, не заботясь об инлайне CSS вручную.

2. Общая структура проекта

Обычно рекомендуют держать Maizzle-шаблоны в отдельной папке email-templates, рядом или внутри вашего Laravel-проекта. Структура может быть следующей:

laravel-app/
  ├── app/
  ├── config/
  ├── resources/
  │   └── views/
  │       └── emails/
  ├── routes/
  └── ...
email-templates/  (корень Maizzle-проекта)
├── components/
│   ├── button.html
│   ├── divider.html
│   ├── spacer.html
│   └── v-fill.html
├── emails/
│   ├── images/
│   └── transactional.html
├── images/
│   └── logo.png
├── layouts/
│   └── main.html
├── node_modules/
├── .editorconfig
├── .gitignore
├── config.js
├── config.production.js
├── package-lock.json
├── package.json
├── README.md
└── tailwind.config.js

3. Установка и инициализация Maizzle 5

Перейдите в корень вашего репозитория Laravel:

cd /path/to/laravel

Затем инициализируйте Maizzle:

# Установка CLI (если ещё не установлено)
npm install --save-dev @maizzle/cli
# Создание базового проекта (скелета)
npx @maizzle/cli new

Установочный скрипт задаст несколько вопросов:

   create-maizzle
│
◇  Where should we create your project?
│  ./email-templates
│
◇  Select a Starter
│  Default
│
◇  Install dependencies?
│  Yes
│
◇  Created project in ./email-templates
│
◇  Installed dependencies 17.373s
│
◇  Next steps: ──────────╮
│                        │
│  cd ./email-templates          │
│  npm run dev           │
│                        │
├────────────────────────╯

После выполнения в email-templates/ появится каталог с файлами:

email-templates/  (корень Maizzle-проекта)
├── components/
│   ├── button.html
│   ├── divider.html
│   ├── spacer.html
│   └── v-fill.html
├── emails/
│   ├── images/
│   └── transactional.html
├── images/
│   └── logo.png
├── layouts/
│   └── main.html
├── node_modules/
├── .editorconfig
├── .gitignore
├── config.js
├── config.production.js
├── package-lock.json
├── package.json
├── README.md
└── tailwind.config.js

4. Настройка путей сборки

4.1 Базовый пример

В config.production.js задайте, куда Maizzle должен складывать скомпилированные письма:

export default {
  build: {
    output: {
      path: "../resources/views",
      extension: "blade.php",
    },
  },
  // А для неэкранированного вывода используем {!! !!}
  expressions: {
    unescapeDelimiters: ['{!!', '!!}']
  },
  css: {
    inline: true,
    purge: true,
    shorthand: true,
  },
  prettify: true,
};

Что делает unescapeDelimiters: ['{!!', '!!}']?

• Если в вашем шаблоне появится {!! какой-то HTML !!}, Maizzle не экранирует угловые скобки <, > и т.п. То есть вы получаете «чистый» HTML-вставку.
• По аналогии с {{ }}, где содержимое экранируется, {!! !!} (в Laravel/Blade) выводит HTML без экранирования. Maizzle даёт похожую возможность на своём уровне (до Blade), если вы хотите сохранить HTML-теги нетронутыми. После выполнения команды

npm run build production

Maizzle возьмёт файлы из emails/ и сгенерирует (скопилирует) их в директорию Laravel ../resources/views/emails/.

5. Игнорирование синтаксиса Blade в Maizzle

Laravel использует директивы Blade вида {{ }} (а также @if, @foreach и т.д.), которые могут конфликтовать с Maizzle, так как Maizzle по умолчанию тоже применяет {{ }} для своих выражений. Maizzle в своей документации предлагает несколько основных способа сохранить/пропустить фигурные скобки, чтобы они «перешли» в финальную версию и были интерпретированы позднее в Laravel . Рассмотрим все:

5.1 @{{ }} для «единовременных» случаев

Если в каком-то месте вам надо, чтобы Maizzle не интерпретировал {{ }}, можно использовать Blade-вдохновлённый синтаксис @{{ }}. В этом случае в итоговом HTML @ будет удалён, а скобки останутся нетронутыми. Например, в emails/example.html (Maizzle-шаблон):

<x-main>
  @{{ $page->markup }}
</x-main>

Результат после сборки Maizzle:

<x-main>
  {{ $page->markup }}
</x-main>

То есть Maizzle «убирает» символ @, а всё, что осталось в {{ }}, останется для следующего шага (например, обработки Blade).

5.2 Тег <raw> для множественных выражений

Если у вас целый блок кода, где есть несколько {{ }}-конструкций (Blade-тегов, чужой движок и т.п.), можно обернуть его в тег <raw>:

<raw>
  <p>The quick brown {{ 1 + 2 }} jumps over the lazy {{ 3 + 4 }}.</p>
</raw>

В финальном HTML тег <raw> будет удалён, а содержимое не будет интерпретироваться Maizzle:

<p>The quick brown {{ 1 + 2 }} jumps over the lazy {{ 3 + 4 }}.</p>

6. Сборка

cd email-templates
npm run build production

В результате Maizzle отдаст готовый HTML, где «на уровне Maizzle» стили будут заинлайнены, а Blade-директивы «дойдут» в Laravel неизменёнными.. 3. Использование в Laravel
Допустим, итоговый файл welcome.html лежит в resources/views/emails/welcome.html. Мы можем вызвать:

Route::get('/test-mail', function () {
    $user = (object)['name' => 'Иван Петров', 'email' => 'test@example.com'];
    Mail::send('emails.welcome', ['user' => $user], function ($message) use ($user) {
        $message->to($user->email)
                ->subject('Привет!');
    });
    return 'Письмо отправлено!';
});

Blade увидит {{ $user->name }} и подставит 'Иван Петров' в письмо.

7. Итоговая схема сборки и отправки

1. Разрабатываете шаблоны в email-templates/emails.
2. Используете один (или несколько) способов «игнорировать» Blade-директивы в Maizzle:
   • @{{ }} для единичных случаев,
   • <raw> для больших блоков,
3. Собираете Maizzle-проект (обычно nmp run build production), результат идёт в папку Laravel resources/views/emails.
4. Отправляете письма через Laravel Mailables. Blade-движок обрабатывает оставшиеся директивы {{ }} и формирует конечный результат для отправки.

8. Заключение

• Maizzle решает боль верстки писем, инлайна CSS и адаптивности,
• Laravel заботится о бизнес-логике рассылки, валидации данных, очередях и пр. Чтобы не конфликтовать с Blade-синтаксисом (или любым другим движком, который использует {{ }}), вы можете:

1. Использовать @{{ }} для одиночных игнорирований.
2. Применять тег <raw> для целых блоков.
   Таким образом, вы получаете мощный, но гибкий процесс: Maizzle занимается версткой email-шаблонов, а Blade — динамикой и данными при отправке писем. Это упрощает разработку и снижает риск конфликтов при сборке. Удачи в реализации!