Architecture6 min read•Audience: Developers
Server-Side Rendering Pipeline
How the PostBrix render engine processes blocks: structural repair, head generation, body rendering, and Handlebars hydration.
Key Takeaways
- Stage 1: AST Normalization and Structural Repair (mjmlFixer ensures valid table hierarchy).
- Stage 2: Partitioning into Head vs Body blocks and responsive CSS generation.
- Stage 3: MJML Compilation via mjml2html with strict validation.
- Stage 4: Handlebars Hydration and HTML minification.
The 4-Stage Rendering Pipeline#
When a template is rendered via the API:
- AST Repair (
mjmlFixer): Checks that every Column is wrapped in a Section, fixing invalid user modifications automatically. - Head Generation: Creates the
<mj-head>containing dark mode overrides, custom font imports, and responsive CSS rules. - MJML Compilation: Calls
mjml2html(mjmlString, { validationLevel: 'strict' })to compile the markup into bulletproof table HTML. - Hydration (
hydrateHtml): Injects customer runtime variables using Handlebars and registers built-in comparison and formatting helpers.
Concurrency and Worker Thread Isolation#
To ensure CPU-intensive MJML compilation never blocks the Node.js event loop:
- Compilation runs inside worker threads or isolated V8 contexts.
- Templates with identical MJML hashes skip Stage 3 entirely and hydrate directly from Redis cache in under 20ms.
Frequently Asked Questions
What happens if MJML compilation throws an error?
PostBrix catches the compilation error and returns an HTTP 500 EngineError payload detailing the exact tag and line number that failed.
Is HTML minification enabled during server-side rendering?
Yes. HTML minification runs automatically on all render API responses, keeping payloads small and protecting against Gmail clipping.