開発者ガイド ​

リポジトリをクローンして chartjs2img を読み解き・拡張したい時の道標。 変更の種類ごとに、どこを見ればいいかをまとめました。

このプロジェクトの実体 ​

2 つのエンジンで Chart.js を描画する薄いラッパーです。既定は skia（skia-canvas によるインプロセス描画・ブラウザ不要）、任意で browser（ヘッドレス Chromium）を選べます:

Node 側のコードは全て bun --compile でそのまま 1 バイナリになります — 開発時にビルドステップ不要。

リポジトリ構成 ​

chartjs2img/
├── src/
│   ├── index.ts         # CLI エントリポイント: argv 解析、サブコマンド振り分け
│   ├── cli.ts           # `render` + `examples` CLI の実装
│   ├── server.ts        # `serve` HTTP サーバー (Bun.serve)
│   ├── renderer.ts      # レンダリングエントリ + エンジン分岐（skia / browser）
│   ├── engine-skia.ts   # skia エンジン（skia-canvas でインプロセス描画・既定）
│   ├── template.ts      # browser エンジンで読み込まれる静的 HTML テンプレート
│   ├── cache.ts         # メモリ内 LRU + TTL キャッシュ
│   ├── semaphore.ts     # 同時実行制御の小さな async セマフォ
│   ├── examples.ts      # 組み込みサンプル (CLI + ギャラリーで共用)
│   ├── version.ts       # VERSION 定数の唯一のソース
│   └── llm-docs/        # モジュールごとの LLM 向け Markdown 片
│       ├── index.ts     # 集約して getLlmDocs() をエクスポート
│       ├── usage.ts
│       ├── chartjs-core.ts
│       ├── plugin-*.ts
│       ├── chart-*.ts
│       └── adapter-*.ts
├── examples/            # JSON 入力 + PNG 出力 (再生成可能)
├── docs/                # VitePress バイリンガルドキュメント
├── .github/workflows/   # CI
├── Dockerfile
├── package.json
└── README.md

コードベースは意図的に小さめ (llm-docs を除くと約 2000 行) — 重い描画 処理は skia エンジンなら engine-skia.ts のインプロセス描画、browser エンジンなら Chromium 内で行われます。コードリーディングで真っ先に読む べきは通常 renderer.ts（エンジン分岐の入口）。

よくあるコントリビューションの流れ ​

「Chart.js プラグインを追加したい」 ​

Chart.js プラグインの追加 を参照。

「プラグイン向けの LLM ドキュメントを追加したい」 ​

LLM ドキュメントの追加 を参照。

「同時実行数 / キャッシュ / ブラウザ挙動をチューニングしたい」 ​

まず アーキテクチャ で構成要素を把握し、モジュール で編集対象のファイルを特定。ほとんどのツマミは環境変数なので再ビルド不要。

「レンダリングのバグに当たった」 ​

まず Chart.js のコンソール出力を確認。browser エンジンでは renderer.ts の page.on('console', …) と window.__chartMessages が Chromium 側と Chart.js 側のエラーの両方を捕捉、skia エンジンでは engine-skia.ts が console.warn / console.error をインプロセスで捕捉します。 それらは X-Chart-Messages (HTTP) または stderr (CLI) で呼び出し元に返ります。 詳しくは エラーハンドリング を参照。

ソースから実行 ​

bun install
bun run dev              # HTTP サーバーが :3000 で起動
bun run cli -- help      # CLI ヘルプ
bun run cli -- llm       # LLM リファレンス

bun run はプロジェクト内のバイナリを優先し、コンパイル済みバイナリ 不要。型チェックは bun run typecheck。

ドキュメントサイトをローカル起動 ​

bun run docs:dev         # VitePress 開発サーバーが :5173 で起動

ドキュメントサイトにバックエンドはありません。docs/en/** と docs/ja/**、および docs/.vitepress/config.ts のサイドバー/ナビ定義を 読むだけ。

次のページ ​

• ライブラリ API (TypeScript) — 任意の Bun / Node プログラムから renderChart などを import。
• アーキテクチャ — HTTP から PNG までのリクエストフロー。
• モジュール — src/*.ts の各ファイル 1 行サマリ。
• 型と HTTP スキーマ — 全インターフェースと全 HTTP ボディ。
• Chart.js プラグインの追加 — 3 ファイル変更、10 行未満。
• LLM ドキュメントの追加 — chartjs2img llm にプラグインのオプション表を追加。
• エラーハンドリング — レンダラエラー / Chart.js エラー / サーバーエラーの違い。