| name | maizzle |
| description | Use when building, editing, or debugging HTML email templates with Maizzle 6 and Tailwind CSS. Triggers on Maizzle 6 projects, email template work, HTML email component usage, email CSS inlining, and email-client compatibility questions. |
| license | MIT |
| metadata | {"author":"Maizzle","version":"1.0.0","homepage":"https://maizzle.com","source":"https://github.com/maizzle/framework","openclaw":{"install":[{"kind":"node","package":"@maizzle/framework","label":"Maizzle"}],"links":{"repository":"https://github.com/maizzle/framework","documentation":"https://maizzle.com/docs"}}} |
Maizzle
Build and send HTML emails that work in all major email clients, with Vue components and Tailwind CSS.
Install
Scaffold a project. The official Maizzle 6 starter is maizzle/maizzle, branch master:
npx maizzle new maizzle/maizzle#master [directory]
For i18n (multi-language) emails, use maizzle/starter-i18n#master.
Add to an existing project:
npm i @maizzle/framework
{ "scripts": { "dev": "maizzle serve", "build": "maizzle build" } }
The dev server generates .maizzle/ (typed .d.ts for auto-imported components and composables). Include it in tsconfig.json. Works with npm, yarn, pnpm, bun.
Basic template
<script setup>
defineConfig({
name: { type: String, default: 'friend' },
})
</script>
<template>
<Layout>
<Container class="max-w-xl">
<Section>
<Heading level="1" class="text-2xl font-semibold mb-4">
Welcome, {{ name }}!
</Heading>
<Text class="text-gray-700 mb-6">
Build HTML emails with Vue and Tailwind.
</Text>
<Button class="bg-blue-600 text-white px-4 py-2 rounded" href="https://maizzle.com">
Learn more
</Button>
</Section>
</Container>
</Layout>
</template>
Components
All built-in components auto-import. Full props/usage in references/COMPONENTS.md; multi-column layout patterns in references/PATTERNS.md.
Document scaffolding — <Layout>, <Html>, <Head>, <Body>, <Tailwind>, <Font>, <Preheader>
Layout primitives — <Container>, <Section>, <Row>, <Column>
Content — <Heading>, <Text>, <Link>, <Button>, <Img>, <Hr>, <Spacer>, <Markdown>, <CodeBlock>, <CodeInline>, <QrCode>
Conditionals & escape hatches — <Outlook>, <NotOutlook>, <OutlookBg>, <Plaintext>, <NotPlaintext>, <Raw>, <NoWidows>, <WithUrl>
AMP4Email — <amp-*> tags pass through verbatim (native, no component resolution). <style amp-custom> is preserved like <style embed> — use @reference "@maizzle/tailwindcss" (not @import) for @apply inside.
Authoring rules
Surgical edits: change only what was asked. Keep existing structure, components, and class lists intact unless explicitly requested.
Reach for built-in components over raw HTML unless explicitly asked for — they encode email-client quirks. Style with Tailwind utilities; arbitrary values are fine. Don't add box-border or align="left" on <Button> (left is the default), or border-solid border-* on <Hr> (use bg-* for color).
No box-sizing in email. Never put padding (or a left/right border) on an element that also sets an explicit width — a <Column> with any w-*/min-w-*/max-w-*, or a <Section>/<Container> given a width. The padding adds to the outer width (content-box), so columns overflow and stack instead of sitting side by side. Put the width on the outer element and the padding on a nested <Section class="px-* border-0"> (or, in hand-rolled tables, on the <td>). A width-less <Section>/<Container> is width:auto, which absorbs padding safely — px-* there is fine. (Bottom/top borders and vertical padding don't affect width, so they're fine on width elements.) See PATTERNS.md → Gutters between columns.
Don't add a leading-* that restates a text-* size's built-in line-height — text-* sizes ship a paired line-height; add leading-* only to deviate (pairs in references/STYLING.md).
Don't add mso-style to repeat padding/bg for Outlook — <Container>, <Section>, <Column> auto-hoist background-color/padding* from your classes onto the MSO <td>. Reserve mso-style for Outlook-only overrides. (Skipped if the element has a horizontal border, or on <Column> with a percentage width.)
What survives across email clients:
- Outlook desktop on Windows uses Word as renderer — no
border-radius, background-image, modern CSS, or media queries. Maizzle's components include MSO ghost tables / VML where needed.
- Gmail clips emails > ~102 KB. Keep templates lean; minify for production.
<QrCode> can be heavy.
- Layout: no flex/grid in older clients. Use
<Row> / <Column>.
- Responsive:
sm: (≤600px), xs: (≤430px) — supported in many clients as progressive enhancement.
- Dark mode:
dark: via prefers-color-scheme. Patchy support; treat as enhancement.
- Images: PNG/JPEG/GIF in production;
<Img dark-src motion-src> for variants. Always set alt and width.
- Spacing: prefer
<Spacer> between block elements (Outlook ignores some margins). Margins are fine on text.
- Avoid:
position: absolute/relative, embedded SVG (Gmail), inline <style> blocks for layout.
For brand color/logo gathering, depth styling guidance, dark mode, and footer patterns, see references/STYLING.md.
Static assets & URLs
Place static files in public/. Reference them via absolute paths (/logo.png). The build copies public/ to the output dir.
Production rewriting (relative → absolute) happens via url.base in config or scoped via <WithUrl>:
export default defineConfig({
url: { base: 'https://cdn.example.com/emails/' },
})
<WithUrl base="https://cdn.example.com/emails/">
<Img src="/logo.png" alt="Logo" width="120" />
</WithUrl>
Both skip absolute URLs, data URIs, protocol-relative, and fragments. UTM/query params: url.query globally or <WithUrl parameters="utm_source=..."> scoped.
Styling overview
Maizzle uses Tailwind CSS 4 via @maizzle/tailwindcss — email-safe resets, MSO utilities, client variants. <Layout> already imports it. For manual control:
<Head>
<style>@import "@maizzle/tailwindcss";</style>
</Head>
Defaults: css.inline, css.purge, css.shorthand, css.safe, css.preferUnitless, css.sixHex, html.decodeEntities are all on. html.minify is off.
Client variants: gmail:, gmail-android:, apple-mail:, ios:, outlook-mac:, outlook-android:, yahoo:, thunderbird:, superhuman:, notion:, spark:, …
Full CSS / HTML / pipeline knobs: references/CONFIGURATION.md and references/TRANSFORMERS.md.
Programmatic render
import { render } from '@maizzle/framework'
const { html, plaintext } = await render('emails/welcome.vue', {
config: { css: { inline: true, purge: true }, plaintext: true },
})
Accepts an SFC path, raw SFC string, or imported Vue component. Runs SSR + full transformer pipeline.
Plaintext
Enable globally:
export default defineConfig({ plaintext: true })
Or per-template via usePlaintext() in <script setup>. Customize destination/extension/strip-HTML opts by passing an object. See references/COMPOSABLES.md.
CLI
npx maizzle … or install globally with npm i -g maizzle. Full command/flag reference: references/CLI.md.
References
references/COMPONENTS.md — every component, props, examples.references/PATTERNS.md — column / responsive layout patterns.references/STYLING.md — Tailwind, color tokens, brand brief, authoring principles.references/CONFIGURATION.md — every config key, defaults, examples.references/COMPOSABLES.md — defineConfig, useConfig, useTransformers, useBaseUrl, useUrlQuery, useEvent, useDoctype, usePlaintext, usePreheader, useHead.references/TRANSFORMERS.md — pipeline order, per-stage behavior.references/CLI.md — every CLI command, flags, and usage.references/CONVERT-REACT-EMAIL.md — porting guide from React Email.references/CONVERT-MAIZZLE-V5.md — upgrade guide from Maizzle 5 to Maizzle 6.
