django-htmx

Django HTMX

Django テンプレート、ビュー、フォーム、権限、サーバー側の検証を主体としたまま、範囲を絞ったページの一部の更新を追加するには、HTMX を使用します。まずは標準の Django を使い、その後、ワークフローの改善に役立つ最小限の HTMX の動作を追加してください。

生成された django-saas-starter プロジェクトでは：

• django-htmx がインストールされており、django_htmx.middleware.HtmxMiddleware によって request.htmx が追加されます。
• htmx.min.js は npm から frontend/static/vendors/js/ にコピーされ、frontend/templates/base_app.html と frontend/templates/base_landing.html に読み込まれます。
• ベーステンプレートでは、すでに htmx:configRequest 時に X-CSRFToken を追加し、window.htmx.config.historyRestoreAsHxRequest = false を設定しています。この設定を機能テンプレートで重複して追加しないでください。
• メニュー、モーダル、開閉状態、軽量なトランジションなど、ブラウザー内だけで扱う状態に限って Alpine.js を使用します。

フレームワークに依存しない HTMX スキル

HTMX の詳しいガイダンスには以下のスキルを使用し、その後、Django のフォーム、ビュー、テンプレート、権限、テストに合わせて適用してください。

• htmx-endpoint-design：リクエスト／レスポンスの契約、ターゲット、スワップ、アウトオブバンド更新、イベントについて説明します。
• htmx-recipes：アクティブ検索、ページネーション、無限スクロール、ポーリング、ダイアログ、クリックして編集、ブーストリンク、その他の一般的なパターンについて説明します。
• htmx-security：XSS、サニタイズ、CSP、CSRF、HTMX の履歴キャッシュに関するリスクについて説明します。
• htmx-realtime：ポーリング、SSE、WebSocket のトレードオフについて説明します。
• htmx-interactivity：Alpine.js との連携、イベントの境界、置き換え可能なターゲットの外部にあるローカル状態について説明します。
• htmx-js-api：プログラムによるリクエスト、htmx.process、イベントの配線について説明します。

リソースの振り分け

現在のタスクに必要なファイルだけを読み込みます。

必要な情報	読むファイル
Django のビュー分岐、レスポンスヘルパー、フォーム、検証	references/django-view-patterns.md
テンプレートのターゲット、スワップ、OOB 更新、Alpine イベント、レシピのメモ	references/template-interaction-patterns.md
セキュリティルール、Django のテスト、レスポンスのアサーション、参考ドキュメント	references/testing-security.md

実装ワークフロー

1. サーバー側の状態を管理する主体を特定します。モデル、クエリーセット、フォーム、サービス、権限、セッション値などです。
2. URL 境界を必要最小限にします。
   • ページ全体と部分表示でクエリーと権限が共通する場合は、request.htmx による分岐を使って既存のビューを再利用します。
   • 操作のコンポーネント契約が限定的な場合や、変更ルールが異なる場合は、専用エンドポイントを作成します。
3. 再利用可能なフラグメントを部分テンプレートに配置します。一般的な場所は frontend/templates/<app>/partials/... またはアプリ内のテンプレートフォルダーです。
4. HTMX レスポンスが返すものと同じ部分テンプレートを読み込んで、ページ全体をレンダリングします。
5. 実用的であれば、リンクやフォームの非 HTMX 時のフォールバック動作を維持します。
6. ビューが request.htmx によって分岐する場合は、通常のリクエストと HTMX リクエストの両方をテストします。

Django のルール

• request.htmx に基づく分岐は、同じ認証、権限確認、データ読み込みの処理が実行された後にのみ行います。
• 同じ URL でフルページと部分コンテンツを異なる形で返すキャッシュ可能なビューでは、@vary_on_headers("HX-Request") を使用します。
• HTMX のヘッダーを手書きするのではなく、django_htmx.http のヘルパーを優先して使用します。 HttpResponseClientRedirect、HttpResponseClientRefresh、 HttpResponseLocation、HttpResponseStopPolling、push_url()、 replace_url()、retarget()、reswap()、reselect()、 trigger_client_event() が該当します。
• 検証の信頼できる情報源として、Django のフォームを維持します。ベースの HTMX ヘッダーが設定されていても、フォームには {% csrf_token %} を含めます。
• HTMX のフォーム送信が無効だった場合は、プロジェクトが 4xx または 422 のスワップを明示的に処理していない限り、通常のステータス 200 で、バインド済みのフォームをレンダリングして返します。
• 破壊的な操作には POST を必須とします。ただし、プロジェクトで DELETE のメソッドオーバーライド方式を意図的に採用している場合は除きます。
• 役割分担を明確にします。HTMX はサーバーへのリクエスト、最新の HTML、履歴の更新、コンポーネント間で共有するサーバー側の情報を担当します。Alpine はローカルのみの状態、キーボードやメニューの動作、一時的な UI 状態、トランジションを担当します。
• 新しい状態に実際のブラウザー URL がふさわしい場合に限り、hx-push-url="true" を使用します。また、直接読み込んだ場合や更新した場合にも、プッシュされた URL でフルページを表示できるようにします。

避けること

• UI の更新に JSON を返さないでください。ただし、HTMX を使わない API が本当に JSON を必要とする場合は除きます。
• 通常の部分更新のために React、Vue、クライアントルーターを追加しないでください。
• ビジネスロジックをテンプレートやブラウザーのイベントハンドラーに記述しないでください。
• 任意のリクエストパラメーターに応じて動作を切り替える、汎用の「htmx エンドポイント」を作成しないでください。明示的な URL とビューを使用します。
• デバウンス、スロットル、または明確な停止条件を設けずに、hx-trigger="keyup" やポーリングを設定しないでください。
• Django の通常の認証、認可、CSRF、フォーム、メッセージの処理パターンを迂回するために HTMX を使用しないでください。