Mjml Backend Components Laravel Package

Getting Started

• Install with composer require juaniquillo/mjml-backend-components. This is a 0.x release, so pin it ("juaniquillo/mjml-backend-components": "0.1.*") until the API stabilises.
• Check the README first for the required MJML runtime. Most MJML backends need either the mjml Node binary or a PHP-side renderer; confirm which one this package expects and add it to your build/deploy image before writing templates.
• Publish anything publishable (php artisan vendor:publish --tag=mjml-backend-components-config, and the views/components tag if present) and read the config file — that is the fastest way to see which components, paths, and rendering options the package actually exposes.
• First use case: build one transactional email (password reset or order confirmation) as an MJML-backed Mailable, render it, and eyeball the HTML output before touching existing templates. This validates the toolchain end-to-end (binary available, components resolving, escaping behaving) in about ten minutes.

Implementation Patterns

• Keep MJML for layout, Laravel for data. Put the skeleton (sections, columns, wrappers) in the package's components and inject dynamic values through Blade/Mailable data. Avoid hand-writing raw HTML inside MJML blocks; that's where attribute and content escaping issues bite.
• Compose via the component set, not raw tags. The point of this package is backend-side components you can reuse across mailables. Build a small internal library (header, footer, button, product row) on top of the package's components, then have every Mailable include those rather than duplicating MJML.
• Render once, cache where it's static. If the package exposes a compiled-output step, wrap it in a helper/service so layout-only emails are memoised; only re-render when dynamic data changes. This keeps mail sending fast and avoids a per-request MJML compile cost.
• Wire it into Mailables normally — return the rendered MJML/HTML from build() or a Content/Envelope view, and keep a plain-text fallback so Mail::fake() assertions and non-HTML clients still work.
• Test at the rendered-HTML level. Assert on the compiled output (presence of expected markup, URLs, and escaped values) rather than on the MJML source. Add one test per shared component so a package upgrade that changes markup surfaces immediately.
• Preview outside production mail flow. A small artisan command or route that renders every registered component with sample data is worth the twenty minutes — MJML failures are otherwise only visible in a real inbox.

Gotchas and Tips

• v0.1.0 is genuinely early. "Small Fixes" and "Missing tags" in the release mean the component surface is still filling out — if a tag you expect isn't there, check the source before assuming a config problem, and consider submitting the component upstream.
• Attribute escaping changed in this release. PR #5 ("Attribute scaping") means attribute values may now be escaped differently than earlier commits. If you copied templates from the repo's pre-release state or from a branch, re-verify any attribute containing quotes, &, or user-supplied strings (alt text, href query params, colours). Escaped output is correct behaviour; double-escaping (&) is not — check for htmlspecialchars calls in your own layer.
• Deployment dependency risk. MJML rendering usually needs Node or a binary present in the container. Add it to your Docker image and CI, not just local dev — "works locally, blank email in staging" is the classic failure.
• Escaping + {!! !!} don't mix. Never bypass Blade escaping for content that flows into MJML attributes; the package's own escaping only covers what it renders.
• Debugging strategy: render to a file (storage/app/mjml-debug.html) and inspect that, not the Mailable object. If the output is empty or the tags are passed through verbatim, the renderer didn't run — check config, binary path, and whether the component is registered.
• Extension point: register custom components through the package's config/registry rather than editing vendor files, so upgrades don't stomp your work.
• Pin dependencies and re-test on bumps. The changelog shows active dependency churn (actions/checkout 4 → 7) and rapid patch-level fixes; treat each 0.x bump as potentially markup-changing until your component tests say otherwise.
• Docs are thin and were typo-fixed in this release. Read the test suite and component source as the authoritative reference; the tests show intended attribute handling and expected output more reliably than the README.