turbodocx-html-to-docx

HTML to DOCX のセットアップ

このスキルは、JavaScript／TypeScript プロジェクトに @turbodocx/html-to-docx を追加します。Puppeteer、Chrome、LibreOffice を使わずに HTML 文字列を Word 文書に変換する、依存関係ゼロのライブラリです。Node.js およびブラウザー（バンドル済みの IIFE／ESM ビルド経由）で動作します。

可能であればサーバー側での実行を優先してください。 サーバー側で実行すると処理が速く、約 2.4 MB のブラウザーバンドルを避けられ、ポリフィルの要件も回避できます。また、（SVG → PNG 変換用の）sharp も利用できます。プロジェクトにバックエンド（Express／Fastify／Next.js API ルートなど）がある場合は、サーバー側の統合をデフォルトにし、プロジェクトが本当に静的である場合、またはユーザーがクライアント側での生成を明示的に希望した場合に限り、ブラウザーバンドルに切り替えてください。

フェーズ 1：プロジェクトの種類を判定する

Glob を使って、プロジェクトの種類を確認します。

1. Node.js／npm ベースのプロジェクト — ルートに package.json が存在します。こちらを優先してください。

   • tsconfig.json も確認し、TypeScript が使われているか判定します。
   • ロックファイルからパッケージマネージャーを判定します。
     • pnpm-lock.yaml → pnpm
     • yarn.lock → yarn
     • bun.lockb → bun
     • package-lock.json またはロックファイルなし → npm
   • package.json の "type": "module" を確認し、ESM と CommonJS のどちらのインポート形式を使うか判定します。
   • サーバーランタイムとクライアントの両方があるプロジェクト（例：Next.js、Remix、Nuxt、SvelteKit）では、サーバールート／ハンドラー／アクションでの実装をデフォルトにしてください。ユーザーが明示的に希望しない限り、クライアントコンポーネントに文書生成を組み込まないでください。
   • **フェーズ 2（npm インストールの手順）**に進みます。

2. ブラウザーのみのプロジェクト — package.json はありませんが、HTML ファイル（*.html）が存在するか、ユーザーが静的ページ／CDN の構成で使いたいと明示しています。この方法を採用する前に、バックエンドで実行する選択肢がないか、簡単にユーザーに確認してください。サーバー側での実行を優先します。ブラウザーでの実行が必要だと確認できた場合は、次の手順に従います。

   • npm のインストールは完全に省略します。このライブラリには、すべての依存関係をインライン化した自己完結型のブラウザーバンドル（dist/html-to-docx.browser.js、約 2.4 MB の IIFE）が含まれています。
   • references/usage.md の ブラウザーでの使用方法のセクションを読み、ポリフィルのスニペット、HTMLToDOCX(...) グローバル、制限事項（sharp が使えない、リモート画像は CORS の制限を受ける、ファイルシステムを利用できない）を確認します。
   • ホストされたコピーまたは CDN ビルドを参照する <script src="..."> を追加し、ユーザーのページに合わせた最小限の動作例を作成します。
   • 以下のフェーズ 2～4 は省略します。ブラウザーでの方法ではインストールは不要です。

3. いずれにも該当しない — package.json も HTML ファイルもありません。作業を進める前に、対象の環境（Node.js、バンドラー、または静的 HTML）をユーザーに確認し、デフォルトとしてサーバー側での実行を推奨します。

フェーズ 2：パッケージをインストールする

判定したパッケージマネージャーに対応するインストールコマンドを実行します。

• npm: npm install @turbodocx/html-to-docx
• pnpm: pnpm add @turbodocx/html-to-docx
• yarn: yarn add @turbodocx/html-to-docx
• bun: bun add @turbodocx/html-to-docx

環境変数は不要です。API キーを必要としないローカルライブラリです。

フェーズ 3：リファレンスを読む

このスキルのディレクトリにある references/usage.md を読みます。API 全体、設定オプション、コード例が記載されています。

フェーズ 4：コードベースを分析してコードを生成する

ステップ 4.1：プロジェクトを調査する

Glob と Read を使って、次の項目を確認します。

• ソースファイルの場所（src/、app/、lib/、ルート）
• 使用中のフレームワーク（Express、Fastify、NestJS、Next.js、Hono、Koa、またはなし）
• 既存のパターン：ルートの定義方法、ファイルの整理方法、命名規則
• TypeScript と JavaScript のどちらを使っているか
• ESM（import）と CommonJS（require）のどちらのスタイルか

ステップ 4.2：ユーザーに確認する

調査で分かったことと、新しいファイルを配置する予定の場所を簡潔に共有します。この内容で問題ないか、ユーザーに確認します。

ステップ 4.3：ヘルパーモジュールを生成する

HTMLtoDOCX を適切なデフォルト値でラップするヘルパーモジュールを作成します。プロジェクトでユーティリティを配置している場所（例：src/lib/、src/utils/、lib/）に配置してください。

ヘルパーには、次の機能を含めます。

• プロジェクトのインポート形式（ESM または CJS）を使用して HTMLtoDOCX をインポートする
• HTMLtoDOCX を呼び出し、Buffer を返す generateDocx(html, options?) のような関数をエクスポートする
• ユーザーが上書きできる、一般的に便利なデフォルト値（フォント、余白）を含める
• プロジェクトで TypeScript を使用している場合は、TypeScript を使用する

ステップ 4.4：統合コードを生成する

プロジェクトの要件に応じて、以下のようにします。

Web サーバー（Express、Fastify、NestJS、Next.js など）の場合： HTML（リクエストボディ内）を受け取り、.docx ファイルを返すエンドポイントを作成します。フレームワークのルーティングパターンに合わせてください。

• Express：Router を使い、res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document') と res.send(buffer) を使用する
• Next.js App Router：app/api/.../route.ts で POST 関数をエクスポートし、new Response(buffer, { headers }) を返す
• NestJS：@Controller と @Post を使用し、@Res() res でバッファーをストリーミングする
• その他のフレームワーク：それぞれの規約に合わせる

レスポンスヘッダーを設定します。

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="document.docx"

（Next.js のようなファイルベースのルーティングを除き）ルートをアプリのメインファイルに組み込みます。

スタンドアロン／スクリプトプロジェクトの場合： HTML（ファイル、stdin、または文字列から）を読み込み、.docx ファイルを書き出すスクリプトを作成します。使用例を示す基本的な HTML 文字列も含めてください。

フェーズ 5：検証と要約

プロジェクトで TypeScript を使用している場合は、npx tsc --noEmit を実行して型エラーを確認します。

次の内容を要約して表示します。

• 作成・変更したファイル
• インストールしたパッケージ
• 使用方法（エンドポイントの場合は curl コマンドの例、スクリプトの場合は実行方法）
• ドキュメントへのリンク：https://docs.turbodocx.com/docs
• カスタマイズできる主なオプション（用紙サイズ、向き、余白、フォント、ヘッダー／フッター）