DOCSEARCHbyAlgolia
Submit Docs

Maizzle

website·Indexed 34 days ago

https://maizzle.com

A modern framework for building HTML emails using Vue and Tailwind CSS. Maizzle provides a suite of components, a pipeline of HTML transformers (such as Purge CSS, Minify, and Shorthand CSS), and a Vite plugin for integration with frameworks like Next.js, Nuxt, Astro, SvelteKit, Laravel, and others.

Tokens
61.4K
Snippets
403
Records
475
Agent score
70%

What's inside Maizzle

  1. Overview of Maizzle email framework

    Maizzle is a modern framework for building HTML emails using Vue Single-File Components (SFCs) and Tailwind CSS. It simplifies email development by providing a component-based workflow and a production build pipeline that handles email client quirks, such as CSS inlining and Outlook fallbacks, automatically.

  2. Overview of the Maizzle Agent Skill

    Maizzle provides an official SKILL—a packaged set of instructions based on the Agent Skills specification—that teaches AI coding agents how to build HTML emails. Instead of guessing, agents using this skill will use built-in Vue components, style with Tailwind CSS 4, configure build pipelines, and adhere to email client constraints. The skill covers template building with components (e.g., <Layout>, <Container>, <Section>, <Button>), CSS inlining, purging, static asset handling, programmatic rendering, and CLI usage.

  3. Overview of Maizzle build events and registration

    Maizzle fires events at key points during the build process. Handlers can be registered in two locations: globally in maizzle.config.ts or locally within a template's <script setup> using the useEvent() composable.

    Events are categorized by scope:

    • Per-template: Handlers fire once per template. SFC handlers registered via useEvent() are scoped to that specific template and cleared between renders.
    • Build-once: Handlers fire a single time per build. SFC afterBuild handlers accumulate across all templates and fire together at the end.

    Note: beforeCreate and beforeRender cannot be registered via useEvent() because they execute before SFCs are parsed.

  4. Use the Maizzle Dev UI for email testing

    The Maizzle Dev UI provides a specialized environment for developing emails with the following features:

    • Live Preview: See changes in real-time without refreshing the page.
    • Device Sizes: Resize the preview window or select specific devices to test responsiveness.
    • Debugging Tools: Inspect generated HTML and plaintext output, check client compatibility, and view linting errors.
    • Test Emails: Send test emails directly from the interface.
    • Command Palette: Quickly navigate emails, emulate dark mode, or access documentation.

  5. Ensure CSS selectors are email-safe with Safe Selectors

    Some email clients, particularly Gmail, discard entire <style> tags if they contain class names with escaped characters (e.g., w-1/2 or sm:block). Maizzle's Safe Selectors transformer normalizes these by replacing unsafe characters with email-safe alternatives in both the <style> tags and the HTML class attributes to keep them in sync.

  6. Choose a Maizzle installation method

    Maizzle can be integrated into your development workflow in three primary ways: as a standalone project, as part of a monorepo setup, or as a Vite plugin within an existing application or Vite-powered framework. If a specific framework guide is not available for your project, the standalone or Vite plugin methods are the recommended alternatives.

  7. Convert 3-digit HEX colors to 6-digit HEX for email compatibility

    The Six-digit HEX transformer converts 3-digit shorthand HEX colors (e.g., #fff) to their 6-digit equivalents (e.g., #ffffff) to ensure compatibility with email clients that do not support shorthand. This transformer specifically targets the bgcolor and color HTML attributes; text content within the HTML is not modified.
    <!-- Input -->
<td bgcolor="#fff" color="#000">
  The #fff and #000 colors are converted to #ffffff and #000000.
</td>

<!-- Output -->
<td bgcolor="#ffffff" color="#000000">
  The #fff and #000 colors are converted to #ffffff and #000000.
</td>

  8. Get current template metadata with useCurrentTemplate()

    Use useCurrentTemplate() to retrieve information about the template file currently being built. It returns an object based on Node's path.parse() containing { root, dir, base, ext, name }. It returns undefined when called outside the per-template scope (e.g., in global build handlers).
    <script setup>
  const file = useCurrentTemplate()
  // Example: if file is 'emails/welcome.vue'
  // file.name === 'welcome'
  // file.ext  === '.vue'
  // file.base === 'welcome.vue'
  // file.dir  === '/abs/path/to/emails'
</script>

  9. Understand the Maizzle transformer pipeline

    After Vue SSR renders a template to HTML, Maizzle processes the output through a pipeline of transformers. These transformers automate email-specific optimizations such as inlining CSS, improving accessibility attributes, and generating plaintext versions of emails.

  10. Email Accessibility (a11y) and Internationalization (i18n) basics

    a11y (accessibility) involves making emails usable for people with disabilities through practices like using HTML text instead of images, providing alt text, and ensuring high color contrast. i18n (internationalization) is the practice of designing content so it can be easily localized for different languages and regions.

  11. Use Maizzle's optimized Tailwind CSS 4 configuration

    Maizzle provides @maizzle/tailwindcss, a custom Tailwind CSS 4 configuration optimized for HTML emails. It includes several email-specific adjustments:

    • Uses px spacing scale instead of rem.
    • Uses a HEX color palette instead of CSS variables.
    • Provides mso- utilities for Outlook-specific styles.
    • Includes email client targeting variants (e.g., gmail:, ios:).
    • Provides prose typography styles and email-safe defaults for box-shadow and border-radius.
    • Performs syntax lowering for modern CSS (nesting, calc(), oklch) and advanced utilities (e.g., space-y-*, *:) to ensure support across email clients.

  12. Render VML shapes for Outlook

    The <Vml> component renders VML shapes for Word-based Outlook versions. It is a general-purpose primitive used for shapes, rounded outlines, dividers, and gradients. For simple background images, <OutlookBg> is a shorter alternative, though <Vml> can perform the same tasks if the type prop is explicitly set.