Webコンテンツを画像に変換：dom-to-image vs html2canvas vs puppeteer

Webアプリケーションで「この画面を画像として保存したい」という要件はよくあります。たとえば、グラフやレポートのエクスポート、SNSシェア用のプレビュー生成、テスト時のビジュアルリグレッションなどです。しかし、一見同じような目的でも、実行環境や精度、制限事項によって適切なツールは大きく変わります。ここでは、dom-to-image、html2canvas、puppeteer の3つを、実際の開発現場で遭遇する課題を中心に比較します。

🖥️ 実行環境：ブラウザ内 vs サーバー外

dom-to-image と html2canvas は、どちらも ブラウザ内で JavaScript として実行されます。つまり、ユーザーの端末で動くフロントエンドコードに直接組み込めます。

// dom-to-image の基本使用例
import domtoimage from 'dom-to-image';

const node = document.getElementById('capture');
domtoimage.toPng(node)
  .then(dataUrl => {
    const img = new Image();
    img.src = dataUrl;
    document.body.appendChild(img);
  });

// html2canvas の基本使用例
import html2canvas from 'html2canvas';

const element = document.querySelector('#capture');
html2canvas(element).then(canvas => {
  document.body.appendChild(canvas);
});

一方、puppeteer は Node.js 環境専用です。ブラウザの外で、ヘッドレス Chrome をプログラムから操作します。そのため、フロントエンドコードに直接埋め込むことはできません。

// puppeteer の基本使用例（Node.js 環境）
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'example.png' });
await browser.close();

💡 ポイント：ユーザーがボタンを押して即座に画像を生成したいなら、dom-to-image か html2canvas。バックエンドで定期的にスクリーンショットを撮るなら、puppeteer。

🎨 レンダリング精度：CSS の再現性はどうか？

変換方式の違い

• dom-to-image は、DOM 要素を一度 SVG に変換し、それを Canvas に描画します。この方法により、transform、filter、clip-path などの高度な CSS プロパティを比較的正確に再現できます。
• html2canvas は、DOM ツリーを走査して、各要素のスタイルを Canvas API で再現しようとします。広範な CSS をカバーしていますが、一部のプロパティは未対応または近似値での再現になります。
• puppeteer は、実際の Chrome ブラウザを使ってページをレンダリングするため、すべての CSS、フォント、画像、Canvas、WebGL などを完全に再現します。

実際のコード比較：CSS transform を含む要素

// dom-to-image：transform を含む要素も高精度で再現
const options = { 
  style: { transform: 'scale(1.2) rotate(5deg)' } 
};
domtoimage.toPng(node, options).then(/* ... */);

// html2canvas：transform は対応しているが、一部の複雑なケースでずれが出る可能性あり
html2canvas(element, {
  useCORS: true,
  allowTaint: false
}).then(/* ... */);

// puppeteer：完全なブラウザレンダリングなので、一切のズレなし
await page.addStyleTag({ content: '#capture { transform: scale(1.2) rotate(5deg); }' });
await page.screenshot({ clip: { x: 100, y: 100, width: 400, height: 300 } });

⚠️ 注意：html2canvas は ::before/::after の疑似要素や、z-index の複雑な重なりを完全に再現できないことがあります。一方、dom-to-image は SVG 変換の制約により、一部の Canvas 描画（例: WebGL）を含む要素は無視されます。

🔒 セキュリティと CORS：外部リソースの扱い

画像やフォントが別ドメインにある場合、CORS（Cross-Origin Resource Sharing） の制約が発生します。

• dom-to-image は、useCORS: true オプションで対応を試みますが、サーバー側が適切な CORS ヘッダーを返していないと失敗します。また、<img> 要素の crossorigin 属性も必要です。
• html2canvas も同様に useCORS: true オプションを提供しますが、内部で画像を再読み込みするため、タイミングやキャッシングの問題で不安定になることがあります。
• puppeteer は、page.setBypassCSP(true) やカスタムリクエストインターセプターを使うことで、より柔軟に CORS 問題を回避できます（ただし、セキュリティリスクに注意）。

// html2canvas の CORS 対応
html2canvas(element, { useCORS: true });

// HTML 側で crossorigin を設定しておく必要あり
// <img src="https://example.com/image.jpg" crossorigin />

// puppeteer で CORS を回避（開発時のみ推奨）
await page.setBypassCSP(true);
await page.goto(url, { waitUntil: 'networkidle0' });

⚙️ 制御粒度：部分キャプチャ vs 全体スクリーンショット

• dom-to-image と html2canvas は、特定の DOM 要素だけを画像化できます。ページ全体ではなく、グラフやカードコンポーネントだけをエクスポートしたい場合に便利です。
• puppeteer は、fullPage: true でページ全体、または clip オプションで特定領域をキャプチャできますが、これは座標ベースです。DOM 要素の動的サイズ変化には追従しません。

// puppeteer で特定要素の位置を取得してキャプチャ
const rect = await page.evaluate(() => {
  const el = document.querySelector('#capture');
  const { x, y, width, height } = el.getBoundingClientRect();
  return { x, y, width, height };
});
await page.screenshot({ clip: rect });

🧪 実行コストとパフォーマンス

• dom-to-image と html2canvas は、ブラウザのメインスレッドで大量の計算を行うため、大規模な DOM や複雑なスタイルでは UI がフリーズする可能性があります。Web Worker での実行は非対応です。
• puppeteer は、別プロセス（Chrome）を起動するため、メモリとCPUを大量に消費します。1リクエストごとにブラウザを起動・終了すると、スケーラビリティに問題が出ます。プーリングや永続セッションの管理が必要です。

🛑 非推奨状態の確認

公式 npm ページおよび GitHub リポジトリを確認したところ、dom-to-image は現在もアクティブにメンテナンスされており、非推奨ではありません。ただし、元々の dom-to-image は更新が止まっており、コミュニティによるフォーク版（例: dom-to-image-more）が存在します。本比較では、公式 npm パッケージとして公開されている dom-to-image を基準としています。

📌 まとめ：選択の判断基準

💡 最後に：実際のプロジェクトでの使い分け

• ダッシュボードのグラフエクスポート機能 → dom-to-image（軽量で高精度）
• SNSシェア用の動的プレビュー生成 → html2canvas（広いブラウザ対応と安定性）
• 定期的なWebページのスクリーンショット監視 → puppeteer（完全なレンダリング保証）

どのツールを選ぶにせよ、自分のユースケースで実際にテストすることが最も重要です。特に、html2canvas と dom-to-image は、同じ HTML でも出力結果が異なることがあります。開発初期に PoC（概念実証）を実施し、期待通りの画像が生成されることを確認しましょう。