takumi

Takumi

このスキルは、Chromium を使わずに JSX、HTML、ノードツリーを PNG／JPEG／WebP／ICO／SVG／アニメーションにレンダリングする場合、ImageResponse の OG ルート、フォント／画像／絵文字、Tailwind の tw とコンパイル済み css の使い分け、WASM のバンドル、または next/og／Satori／v1 からの移行など、Takumi／takumi-js に関わる作業で使用します。

スナップショット：[email protected] と、それに対応する @takumi-rs/core、@takumi-rs/wasm、@takumi-rs/helpers、@takumi-rs/image-response（2026-09-15 リリース。2026-10-01 時点でも npm の latest）。関連する PDF パッケージは [email protected] です。バージョンが異なる場合は、source-map.md を参照して情報を更新してください。

ワークフロー

1. コードを変更する前に、ローカルの構成を確認します。
   • パッケージ：takumi-js（すべてをまとめた推奨パッケージ）、必要に応じて @takumi-rs/core、@takumi-rs/wasm、@takumi-rs/helpers。
   • バージョン：v2.14 を対象にします。v1 の API（loadFonts、fetchedResources、createImageResponse）はレガシーとして扱います。stylesheets と keyframes レンダリングオプションは非推奨です（v3 で削除）。代わりに css を使用してください。
   • ランタイム：Node／Bun のネイティブ版、Edge／Cloudflare Workers／ブラウザーの WASM 版。takumi-js が自動で選択します。takumi-js と @takumi-rs/wasm には Node >=20.19 が必要です。クロスコンパイルでデプロイする場合は、プラットフォーム別のネイティブパッケージを固定してください。
   • エントリーポイント：render／renderSvg／renderAnimation、または takumi-js/response の ImageResponse。takumi-js/node または takumi-js/wasm でバックエンドを指定できます。ブラウザーバンドルでは takumi-js/wasm/no-init と takumi-js/wasm-url を使用します。
   • スタイリング方法：インラインの style、組み込みの tw、<style>、または css（文字列、リスト、ルールオブジェクト）。
2. 最新の動作を求められた場合、インストール済みのバージョンが不明な場合、または css／WASM のバンドル／アニメーションに関わる作業では、ドキュメントを更新します。source-map.md から始めてください。
3. インストール、パッケージ、render／ImageResponse、入力、キャッシュ、キャンバスのサイズ設定については、setup-core.md を参照してください。
4. フォント、画像、絵文字、tw、css、テーブル、リストについては、fonts-images-styling.md を参照してください。
5. フォーマット、DPR、SVG、アニメーション、生データ／ffmpeg フレームについては、formats-animation.md を参照してください。
6. Next.js、TanStack Start、Workers、Nitro、WASM バンドラー、その他のホスト環境については、frameworks.md を参照してください。
7. v1 から v2 への移行、2.5 から 2.14 への変更点、Satori／next/og からの移行、トラブルシューティングについては、pitfalls-migration.md を参照してください。
8. コマンド例では bun／bunx を優先してください。生成するコードに Fumadocs の注釈（[!code --]、[!code highlight]）を絶対に含めないでください。

判断

• デフォルトでは render(node, options) または new ImageResponse(node, options) を使用してください。複数回のレンダリングでフォント／画像のキャッシュを再利用する場合にのみ、takumi-js/node（または @takumi-rs/core）の Renderer を使用してください。
• render、renderSvg、renderAnimation（および napi／WASM の Renderer メソッド）は、必ず await してください。
• ルートに w-full h-full（または width／height: 100%）を指定してください。キャンバスサイズだけではルートは引き伸ばされません。
• fonts（配列または Promise）を使って、呼び出しごとにフォントを渡してください。組み込みのフォールバックは Geist Latin、ウェイトは 300–800 です。それ以外（CJK、カスタムブランドなど）は登録してください。汎用ファミリーの sans-serif は組み込みフォントではなく、登録済みファミリーに解決されます。takumi-js/helpers の googleFonts を優先してください。ウェイト範囲／axes を指定すると、可変フォントが読み込まれます。font-mono が解決されるよう、generic: "monospace" などを指定してください。
• 非推奨の stylesheets より css を優先してください。コンパイル済みの Tailwind、Tailwind v4 のソース（@theme、@import "tailwindcss"、@apply）、またはルールオブジェクト { selector, style } を渡してください。css と stylesheets は同時に渡さないでください。
• tw は組み込みの Tailwind サブセットです。css に @import "tailwindcss" が含まれていない限り、Preflight は適用されません。レイヤーなしのスタイルシートルールはユーティリティより優先されます。! を付けると優先順位が逆転します。:root／@theme のトークンがユーティリティに反映されます（--color-brand-500 → bg-brand-500）。
• 裸の <div> は（CSS の）display: block です。Satori のように flex にはなりません。古いテンプレートで明示的に指定された display: flex は引き続き機能します。
• ユーザー入力がリモートの src／背景 URL に影響する可能性がある場合は、images.allowUrl を設定してください（SSRF 対策）。信頼境界をまたいで fetchCache を共有しないでください。フェッチのタイムアウトのデフォルトは 30s（5s ではありません）です。
• マルチスレッドでレンダリングする場合は、Node／Bun ではネイティブの takumi-js/node を優先してください。WASM はシングルスレッドです。ブラウザー／webpack／Turbopack では、Vite の ?url エントリではなく wasm/no-init + wasm-url を使用してください。
• next/og からの置き換えは、インポートを takumi-js/response に変更するだけです。プロジェクトが Takumi 以外の理由ですでに Chromium／Satori+sharp パイプラインに依存している場合を除き、これらの使用は避けてください。
• 請求書／レポートには、takumi-js ではなく takumi-pdf を使用してください。

検証

リポジトリに既存のチェックがある場合は、そちらを優先してください。Takumi に関する重要な作業では、関連する項目を実施してください。

• ルートハンドラー／レンダリングスクリプト（ImageResponse、RenderOptions、css）の型チェックを行います。
• 静的 OG 画像（1200×630）を 1 つ試験レンダリングし、出力バイト列を開くか、ルートにアクセスします。
• ルートがキャンバス全体を埋めることを確認します。レイアウトがおかしい場合は drawDebugBorder: true を使用します。
• CJK／カスタムフォントでは、fonts／googleFonts が設定され、豆腐文字が表示されないことを確認します。
• デプロイ時には、対象の OS／アーキテクチャに対応するネイティブバインディングがあること（または Workers で WASM パスを使用すること）を確認します。takumi-js／WASM には Node 20.19+ が必要です。
• v1 から v2 への移行後は、await、fonts／images オプション、new ImageResponse(jsx, opts) を再確認します。
• 2.5 から 2.14 への移行後は、stylesheets だけでなく css を使っていること、フェッチのタイムアウト、64 MiB／64 MP の上限、WASM バンドラーのエントリを再確認します。