API

Use the Maizzle API to compile a string to an HTML email.

Usage

First, require() the render method in your application:

app.js
const { render } = require('@maizzle/framework')

Then call it, passing it a string and an options object:

app.js
const { render } = require('@maizzle/framework')
render(`html string`, options)
.then(({html, config}) => console.log(html, config))

The render method returns an object containing the compiled HTML and the Environment config that was computed for it.

Options

options is an object with the following structure:

{
tailwind: {
config: {},
css: '',
compiled: '',
},
maizzle: {},
beforeRender() {},
afterRender() {},
afterTransformers() {},
}

tailwind

Pass in a custom Tailwind CSS configuration, or a pre-compiled CSS string.

OptionTypeDefaultDescription
configObjectundefinedA Tailwind CSS config object.
cssString@tailwind components; @tailwind utilities;A CSS string. Will be compiled with Tailwind CSS, so it may use PostCSS syntax. To use Tailwind, it needs to include at least @tailwind utilities
compiledStringundefinedA pre-compiled CSS string, to use as-is. This will skip Tailwind compilation, resulting in faster render speed.

maizzle

The Maizzle Environment configuration object.

TypeDefaultDescription
Object{}A Maizzle config object.

Example

app.js
const { render } = require('@maizzle/framework')
let html = `---
title: Using Maizzle on the server
---
<!DOCTYPE html>
<html>
<head>
<style>{{{ page.css }}}</style>
</head>
<body>
<table>
<tr>
<td class="button">
<a href="https://maizzle.com">Confirm email address</a>
</td>
</tr>
</table>
</body>
</html>`
render(html,
{
tailwind: {
config: require('./tailwind.config.js'),
css: `
.button { @apply rounded text-center bg-blue-500 text-white; }
.button:hover { @apply bg-blue-700; }
.button a { @apply inline-block py-4 px-6 text-sm font-semibold no-underline text-white; }
`,
},
maizzle: require('./config.js')
}
).then(({html}) => console.log(html)).catch(error => console.log(error))

Templating

Of course, templating tags are available when using Maizzle programmatically.

app.js
let html = `---
title: Using Maizzle programmatically
---
<x-main>
<!-- your email HTML... -->
</x-main>`

Gotchas

Since the options object you can pass to the render method is optional, there are a few gotchas that you need to be aware of.

Default Tailwind

If you don't specify a Tailwind config object, Maizzle will try to compile Tailwind using tailwind.config.js at your current path.

If the file is not found, Tailwind will be compiled with its default config.

The default config is not optimized for HTML email: it uses units like rem and CSS properties that are used for web design and which have little to no support in the majority of email clients.

Also, the default Tailwind config will not include any content paths that should be scanned for generating utility classes.

Transformers

Most Transformers, such as CSS inlining or minification, are opt-in: they transform content only when you enable them. Since you don't need to pass in a Maizzle config object, this means that most of them will not run.

The following Transformers always run:

  • Markdown (can be disabled)
  • Prevent Widows
  • Remove Attributes - removes empty style attributes by default
  • Filters - supports <style tailwindcss|postcss> tags and provides various text filters

CSS Output

The string to be compiled with render() must include {{{ page.css }}} in a <style> tag inside the <head>, otherwise no CSS will be output or inlined:

<!DOCTYPE html>
<html>
<head>
<style>{{{ page.css }}}</style>
</head>
<body>
...
</body>
</html>
Copyright © 2024 Maizzle SRLBrand policy
Edit this page on GitHub