Claude CodeでPlotlyのグラフを単一HTMLに書き出す — サイズと共有方法

Plotlyのグラフは、write_htmlで1枚のHTMLに書き出せます。ブラウザで開けば、ホバー、拡大、凡例のクリックがそのまま動きます。落とし穴はファイルサイズです。既定のままだと、グラフ1枚のために数MBのHTMLができます。

Claude Codeに「グラフをHTMLにして」とだけ頼むと、この既定値で出てくることが多くなります。渡し先がメールなのか社内Wikiなのか、閲覧者がオフラインなのかを先に決めておくと、指示が短く済みます。ここではinclude_plotlyjsの選択肢、静的画像との使い分け、Claude Codeへの頼み方と検証までを順に説明します。

なぜ単一HTMLが数MBになるのか

write_htmlで出るファイルは、既定で完全に自己完結したHTMLです。グラフを動かすためのPlotly.js本体がファイルの中に丸ごと埋め込まれるため、サイズが膨らみます。入門ページはこれを「5Mb+」と書き、APIリファレンスのinclude_plotlyjsの説明は埋め込みを「約3MB」としています。同じ公式内で数字に幅があり、実際の値はPlotlyのバージョンで変わります。数MBと見ておけば足ります。

大きい理由は、データではなくライブラリです。10点の散布図でも、100万点のヒートマップでも、ライブラリ分の数MBは変わりません。逆に言えば、サイズを削る手はライブラリの置き場所を変えることに集約されます。

include_plotlyjsの選択肢を比べる

Plotly.jsをどこに置くかは、include_plotlyjsで決まります。write_htmlの既定値はTrueです。

'cdn'は、バージョンを合わせたCDNのURLを読みに行きます。ファイルは軽くなりますが、閲覧者がネットワークにつながっている必要があります。ライブラリを外に出して軽くする考え方は、フロントエンドのバンドルサイズ削減と同じです。

'directory'は、複数のグラフを同じフォルダに出すときに効きます。plotly.min.jsはフォルダに1つだけ置かれ、すでにあれば上書きされません。10枚のグラフを出しても、ライブラリの実体は1回分です。ただしHTMLだけをメールに添付すると、JSが付いてこないので動きません。

Falseは、すでにPlotly.jsを読み込んでいるページにグラフの断片を差し込む用途の値です。full_html=Trueのまま使うと動かないHTMLになると、リファレンスにあります。

静的画像(kaleido)に切り替える場面

PlotlyにはHTMLのほかに、PNG・JPEG・WebP・SVG・PDFへ書き出すwrite_imageがあります。画像出力にはKaleido 1.0.0以上が必要です。Kaleido 1.0.0以降はChromeを同梱しないため、マシンにChrome(またはChromium)が入っている必要があります。無ければplotly_get_chromeコマンドかplotly.io.get_chrome()で入れられます。

使い分けの軸は、閲覧者が何をするかです。

• 動かして読む(ホバーで値を見る、範囲を拡大する、系列を消す) → HTML
• 資料やPDFに貼る、チャットでプレビューさせる → 静的画像
• 論文や印刷物 → SVGかPDF

複数の図はplotly.io.write_imagesでまとめて書き出せます。公式は、write_imageを図の数だけ呼ぶより速いとしています。画像にした時点でホバーは消えるので、HTMLと画像の両方を出し、メールには画像、詳細を見たい人にはHTMLという渡し方も現実的です。

Claude Codeに頼むときの指示

claude -pでパイプ経由に渡す使い方は、Claude Codeの公式ワークフロー集にあります。対話で頼む場合も同じで、指示に共有方法を入れるのがコツです。

次は指示文の一例です。

data/sales.csv を読み、月別売上の折れ線グラフを Plotly で作って
out/sales.html に書き出して。メールに添付するので、
オフラインで開ける形にして。書き出した後に、ファイルサイズと
scriptタグの参照先を表示して。

「メールに添付」と書いておくと、include_plotlyjsはTrueのままで良いという判断につながります。社内サーバーに置くなら、「CDNを参照して軽くして」と書きます。

毎回書くのが面倒なら、CLAUDE.mdに規約として置けます。

## グラフの書き出し(Plotly)
- HTML は fig.write_html で出し、include_plotlyjs を必ず明示する
- 添付用は True、サーバー設置用は 'cdn'、同一フォルダに複数出すなら 'directory'
- 書き出し後に ls -l でサイズを確認し、報告に含める
- 画像が必要なときは write_image(kaleido)を使い、HTML と別ファイルにする

書き出した後の検証

HTMLは開いて目で確かめたくなりますが、サイズと参照先は機械で確かめたほうが確実です。Claude Codeにシェルを実行させ、その出力を読ませます。

ls -l out/sales.html
grep -o '<script[^>]*src="[^"]*"' out/sales.html

Trueで書いたHTMLは、外部のsrcを持つscriptタグが出ないのが期待値です。'cdn'なら外部URLを指すタグが1つ出ます。これが期待と違えば、指示と設定がずれています。サイズが数MBあるのに「軽くした」と報告されたときも、この2行で見抜けます。

実行環境にPlotlyが入っているかは、プロジェクトごとに違います。書き出し前にClaude Codeへ依存の確認を頼んでおくと、途中のインポートエラーを避けられます。

HTMLテンプレートに差し込む

既存のページにグラフを入れたいときは、to_html(full_html=False)でdiv部分だけを文字列として取り出せます。Jinja2のテンプレートに{{ fig }}を置き、そこへ差し込む手順が公式にあります。複数のグラフを並べたダッシュボードを1ファイルで作る流れは、Claudeのdataプラグインでダッシュボードを作る手順にあります。スライダーで値を動かすHTMLを作るなら、playgroundプラグインも候補です。

この場合、include_plotlyjsはページ側で1回だけ決めます。グラフごとにTrueにすると、同じライブラリが何度も埋め込まれます。公式の例にも、外部のPlotly.jsを指す設定を検討するよう注記があります。テンプレートの<meta charset="utf-8">も欠かせません。負の符号などが文字化けするためです。

高さを画面に追従させたいときは、autosize=Trueとheight=Noneを図のレイアウトに、responsiveをTrueにした設定をto_htmlに渡し、default_height="80vh"のように指定します。

数式ラベルにLaTeXを使うなら、include_mathjaxも指定します。'cdn'なら表示できますが、ネットワークが前提になります。

write_htmlのほかの引数

サイズ以外にも、共有を意識すると触る引数があります。いずれもwrite_htmlのリファレンスにある引数です。

• config: Plotly.jsの図の設定を辞書で渡します。responsiveもここです
• default_width / default_height: 既定はどちらも'100%'です。固定サイズで見せたいときに変えます
• auto_open: Trueにすると書き出し後にブラウザで開きます。既定はFalseです
• div_id: 図のdivのIDを指定します。複数の図を1ページに置くときに、名前の衝突を避けられます
• post_script: 図の作成直後に実行するJavaScriptを渡せます。クリックなどのイベントハンドラを足す用途です
• auto_play: アニメーションのフレームを持つ図が、読み込み時に自動再生するかどうかです。既定はTrueです

Claude Codeに頼むときは、これらを全部並べなくても構いません。「幅いっぱいに広がる形で」「アニメーションは自動再生しない」のように結果を言えば、対応する引数を選んでくれます。選ばれた引数が意図どおりかは、生成されたスクリプトのwrite_htmlの行を読めば分かります。

つまずきやすい点と切り分け

HTMLを渡した相手から「グラフが出ない」と返ってきたとき、原因はほぼ次のどれかです。

画像側の典型は、Chromeが見つからないケースです。Kaleido 1.0.0以降はChromeを同梱しないので、write_imageが失敗したらplotly_get_chromeで入れるか、plotly.io.get_chrome()をPythonから呼びます。Kaleidoは1.0.0以上が必要なので、pip install --upgrade kaleidoでバージョンを揃えてから再実行します。

画像はHTMLと違い、メールに貼ってもプレビューで見えます。ただしホバーで値を読む使い方はできなくなるので、読み手が数値を確かめたいグラフは、画像の横にHTMLも付ける形が無難です。

書き出しスクリプトを再利用する形にする

一度きりの書き出しなら、指示文だけで足ります。毎週同じグラフを配るなら、スクリプトとして残すほうが楽です。Claude Codeに次のような関数を作らせ、共有先ごとの違いを引数にします。

import plotly.io as pio
 
def export(fig, path, target):
    # target: "mail" | "server" | "folder"
    mode = {"mail": True, "server": "cdn", "folder": "directory"}[target]
    pio.write_html(fig, path, include_plotlyjs=mode)

共有先の取り違えを防ぐには、この関数のテストを書かせる手もあります。書き出したHTMLを読み、src属性の有無を調べるテストなら、数行で書けます。サイズの上限をテストに入れておけば、Trueのまま'server'向けに出す事故も検知できます。

判断の早見

迷ったら、次の順で考えます。

1. 受け取る人は動かして読むか。読むならHTML、読まないなら画像
2. HTMLなら、オフラインで開かせるか。開かせるならTrue
3. 置き場所が決まっているなら、'cdn'か'directory'でサイズを落とす
4. 書き出した後に、サイズとsrcをコマンドで確かめる

まとめ

Plotlyの単一HTMLが重いのは、データではなくライブラリが埋め込まれるからです。渡し先がオフラインならそのまま、サーバーに置くなら'cdn'、同じフォルダに複数出すなら'directory'と、共有方法から値が決まります。Claude Codeには共有方法を指示文かCLAUDE.mdに書き、書き出し後はls -lとgrepで結果を確かめさせると、サイズの取り違えを防げます。