Build process
When you run maizzle build, your Templates go through a series of events that compile them to plain HTML and apply various, email-specific transformations.
To get a better understanding of how Maizzle builds your emails, here's a step-by-step guide of what's going on under the hood.
Environment config
First, a global configuration object is computed by merging your Environment config on top of the base config.js.
For example, running maizzle build production will tell Maizzle to look for the config.production.js file at your current location, and merge it on top of config.js.
When running maizzle build or maizzle serve, only the base config.js will be used.
beforeCreate()
The beforeCreate event (CLI-only) is triggered, giving you access to the config before Maizzle loops over your Templates to compile them.
Clean destination
The destination directories that you have defined under build.output.path in your environment config are deleted.
Compile templates
Each Template file is parsed and compiled:
- Maizzle reads the Template file
- It extracts its Front Matter
- A unique Template
configis computed by merging the Template's Front Matter keys with the Environmentconfig - beforeRender() event is triggered
- The HTML is rendered with PostHTML
Your Environment name and allconfigoptions (including any you defined in Front Matter) are exposed under thepageobject, which you can access through expressions.
PostHTML plugins that are used as part of the rendering process:- envTags - core plugin that enables
<env:?>tags - envAttributes - core plugin that enables attributes like
src-{env} - expandLinkTags - core plugin that expands local
<link>tags into<style>tags - postcssPlugin - this is where the Tailwind CSS magic happens
- fetchPlugin - enables the
<fetch>tag posthtml-component- the PostHTML plugin that powers Maizzle's components
- envTags - core plugin that enables
- afterRender() event is triggered
Transformers
The compiled HTML is now passed on to a series of Transformers. Most of them are enabled by default, but some need to be explicitly enabled in your config.js.
The order in which they're executed is exactly as follows:
- coreTransformers - remove
<plaintext>tags when developing locally, enableno-inlineattribute for<style>tags - safeClassNames - escaped characters in
<head>and<body>CSS classes are replaced with email-safe alternatives - filters - Liquid-like filters are applied to the HTML
- markdown is compiled
- widowWords - widow words are prevented in tags with the
prevent-widowsattribute - attributeToStyle - translates HTML attributes to inline CSS
- inlineCSS - CSS is inlined
- removeAttributes - HTML attribute removal based on your config
- shorthandCSS - longhand CSS in
styleattributes is converted to shorthand-form - addAttributes - user-configured attributes are added to tags
- baseURL - a base URL is prepended to configured attribute values
- urlParameters - configured parameters are added to URLs
- sixHex - ensures six digit HEX color codes are used in
bgcolorandcolorattributes - posthtmlMSO -
<outlook>tags are replaced with the correct MSO comments - purgeCSS - unused CSS is removed from
<style>tags and HTML attributes - templateTag -
<template>tags are replaced with their content - replaceStrings - strings are replaced based on your config
- prettify - HTML is prettified
- minify - HTML is minified
afterTransformers()
The afterTransformers event is triggered.
Plaintext
A plaintext version is created at the configured location, if plaintext was enabled.
Write to disk
The compiled HTML is saved at the configured location, with the configured extension.
Copy static files
All files and folders in build.static.source are copied to build.static.destination.
afterBuild()
The afterBuild event is triggered (CLI-only).