maizzle

Maizzle

Vue コンポーネントと Tailwind CSS を使用して、主要なすべてのメールクライアントで正しく表示される HTML メールを作成して送信します。

インストール

プロジェクトをスキャフォールディングします。公式の Maizzle 6 スターターは maizzle/maizzle、ブランチは master です。

npx maizzle new maizzle/maizzle#master [directory]

i18n（多言語）メールには、maizzle/starter-i18n#master を使用してください。

既存のプロジェクトに追加する場合：

npm i @maizzle/framework

// package.json
{ "scripts": { "dev": "maizzle serve", "build": "maizzle build" } }

開発サーバーによって .maizzle/（自動インポートされるコンポーネントとコンポーザブル用の型定義 .d.ts）が生成されます。これを tsconfig.json に含めてください。npm、yarn、pnpm、bun に対応しています。

基本テンプレート

<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>

コンポーネント

組み込みコンポーネントはすべて自動インポートされます。すべての props と使い方については references/COMPONENTS.md、複数列レイアウトのパターンについては references/PATTERNS.md を参照してください。

ドキュメントのスキャフォールディング — <Layout>、<Html>、<Head>、<Body>、<Tailwind>、<Font>、<Preheader>

レイアウトの基本要素 — <Container>、<Section>、<Row>、<Column>

コンテンツ — <Heading>、<Text>、<Link>、<Button>、<Img>、<Hr>、<Spacer>、<Markdown>、<CodeBlock>、<CodeInline>、<QrCode>

条件分岐とエスケープハッチ — <Outlook>、<NotOutlook>、<OutlookBg>、<Plaintext>、<NotPlaintext>、<Raw>、<NoWidows>、<WithUrl>

AMP4Email — <amp-*> タグはそのまま出力されます（ネイティブ対応のため、コンポーネント解決は行われません）。<style amp-custom> は <style embed> と同様に保持されます。内部の @apply には、@import ではなく @reference "@maizzle/tailwindcss" を使用してください。

オーサリングルール

外科的な編集を行います。依頼された内容だけを変更してください。明示的に依頼されていない限り、既存の構造、コンポーネント、クラスリストをそのまま維持してください。

明示的に依頼されていない限り、素の HTML より組み込みコンポーネントを優先してください。メールクライアント特有の挙動が組み込まれています。Tailwind ユーティリティでスタイルを指定してください。任意の値を使ってもかまいません。<Button> に box-border や align="left"（左揃えがデフォルトです）を追加したり、<Hr> に border-solid border-* を追加したりしないでください（色には bg-* を使用します）。

メールではボックスサイズを指定できません。 明示的な幅を設定する要素に padding（または左右の border）を指定しないでください。対象は、w-*／min-w-*／max-w-* のいずれかが指定された <Column>、または width が指定された <Section>／<Container> です。padding は外側の幅（content-box）に加算されるため、カラムがあふれて横並びではなく縦に積み重なります。幅は外側の要素に指定し、padding はネストされた <Section class="px-* border-0">（または手書きのテーブルでは <td>）に指定してください。幅を指定していない <Section>／<Container> の幅は auto となり、padding を安全に吸収するため、ここでの px-* は問題ありません。（上下の border と垂直方向の padding は幅に影響しないため、幅を指定した要素に設定しても問題ありません。）「PATTERNS.md → カラム間のガター」を参照してください。

text-* のサイズに組み込まれた行の高さを重ねて指定する leading-* は追加しないでください。text-* のサイズには対応する line-height が設定されています。leading-* はそれを変更する場合にのみ追加してください（対応関係は references/STYLING.md を参照）。

Outlook 用に mso-style を追加して padding／背景色を重複指定しないでください。<Container>、<Section>、<Column> は、クラスから background-color／padding* を MSO の <td> に自動で引き上げます。mso-style は Outlook 専用の上書きに限って使用してください。（要素に水平方向のボーダーがある場合、または <Column> の幅がパーセンテージの場合はスキップされます。）

メールクライアント間で維持されるもの：

• Windows の Outlook デスクトップ版はレンダラーとして Word を使用します。border-radius、background-image、モダン CSS、メディアクエリは使用できません。Maizzle のコンポーネントには必要に応じて MSO のゴーストテーブル／VML が含まれています。
• **Gmail は約 102 KB を超えるメールを切り詰めます。**テンプレートを軽量に保ち、本番環境向けに圧縮してください。<QrCode> はサイズが大きくなる場合があります。
• レイアウト：古いクライアントでは flex／grid を使用できません。<Row>／<Column> を使用してください。
• レスポンシブ：sm:（600px 以下）、xs:（430px 以下）は多くのクライアントでプログレッシブエンハンスメントとしてサポートされています。
• ダークモード：prefers-color-scheme を使った dark:。サポートにはばらつきがあるため、機能強化として扱ってください。
• 画像：本番環境では PNG／JPEG／GIF を使用してください。バリエーションには <Img dark-src motion-src> を使用します。必ず alt と width を設定してください。
• 間隔：ブロック要素の間には <Spacer> を優先してください（Outlook は一部のマージンを無視します）。テキストにはマージンを使用しても問題ありません。
• 避けるもの：position: absolute/relative、埋め込み SVG（Gmail）、レイアウト用のインライン <style> ブロック。

ブランドカラー／ロゴの収集、奥行きのあるスタイル指定、ダークモード、フッターのパターンについては、references/STYLING.md を参照してください。

静的アセットと URL

静的ファイルは public/ に配置してください。絶対パス（/logo.png）で参照します。ビルド時に public/ の内容が出力ディレクトリにコピーされます。

本番環境での書き換え（相対 URL → 絶対 URL）は、設定の url.base または <WithUrl> でスコープを限定して行います。

// maizzle.config.ts
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>

どちらも絶対 URL、データ URI、プロトコル相対 URL、フラグメントはスキップします。UTM／クエリパラメーターは、全体には url.query、スコープを限定する場合は <WithUrl parameters="utm_source=..."> を使用します。

テンプレートタグ（{{、{%、<% など。Twig／Liquid／Blade／ERB など）のいずれかで始まる値には、プレフィックスが付与されません。特定の要素の URL を記述どおりに保つには、その要素（HTML タグまたはコンポーネント）に no-base-url を追加してください。この指定はその要素のみに適用され、子要素には適用されません。また、出力時に削除されます。

<Img src="/logo.png" alt="Logo" width="120" no-base-url />

スタイル設定の概要

Maizzle は @maizzle/tailwindcss を通じて Tailwind CSS 4 を使用します。メール対応のリセット、MSO ユーティリティ、クライアントバリアントが含まれています。<Layout> ではすでにインポートされています。手動で制御する場合は、次のようにします。

<Head>
  <style>@import "@maizzle/tailwindcss";</style>
</Head>

デフォルトでは、css.inline、css.purge、css.shorthand、css.safe、css.preferUnitless、css.sixHex、html.decodeEntities がすべて有効です。html.minify は無効です。

クライアントバリアント：gmail:、gmail-android:、apple-mail:、ios:、outlook-mac:、outlook-android:、yahoo:、thunderbird:、superhuman:、notion:、spark:、……

CSS／HTML／パイプラインの全設定項目については、references/CONFIGURATION.md と references/TRANSFORMERS.md を参照してください。

プログラムからのレンダリング

import { render } from '@maizzle/framework'

const { html, plaintext } = await render('emails/welcome.vue', {
  config: { css: { inline: true, purge: true }, plaintext: true },
})

SFC のパス、生の SFC 文字列、またはインポート済みの Vue コンポーネントを受け付けます。SSR と完全なトランスフォーマーパイプラインを実行します。

プレーンテキスト

全体で有効にするには、次のようにします。

export default defineConfig({ plaintext: true })

または、<script setup> で usePlaintext() を使うと、テンプレートごとに有効にできます。オブジェクトを渡すと、出力先／拡張子／HTML 除去のオプションをカスタマイズできます。詳しくは references/COMPOSABLES.md を参照してください。

CLI

npx maizzle … を実行するか、npm i -g maizzle でグローバルにインストールします。コマンドとフラグの全リファレンスについては、references/CLI.md を参照してください。

リファレンス

• references/COMPONENTS.md — すべてのコンポーネント、props、使用例。
• references/PATTERNS.md — カラム／レスポンシブレイアウトのパターン。
• references/STYLING.md — Tailwind、カラートークン、ブランド概要、作成の原則。
• references/CONFIGURATION.md — すべての設定キー、デフォルト値、使用例。
• references/COMPOSABLES.md — defineConfig、useConfig、useTransformers、useBaseUrl、useUrlQuery、useEvent、useDoctype、usePlaintext、usePreheader、useHead。
• references/TRANSFORMERS.md — パイプラインの順序と各ステージの動作。
• references/CLI.md — すべての CLI コマンド、フラグ、使用方法。
• references/CONVERT-REACT-EMAIL.md — React Email からの移行ガイド。
• references/CONVERT-MAIZZLE-V5.md — Maizzle 5 から Maizzle 6 へのアップグレードガイド。