htmx 2.0 - 1.xからの主な変更点

5分 で読める | 2025.12.11

公式ドキュメント
JS

リリース日: 2024年6月17日

記事公開日: 2025年12月11日

最終確認日: 2026年7月25日

htmx 2.0は、htmx 1.xの基本的な考え方を保ちながら、古い互換処理や非推奨機能を整理したメジャーリリースです。

この記事は2.0公開時の差分と移行時の確認事項に絞ります。 htmxの基本的な使い方は、htmxの基本を先に読んでください。

2.0の主な変更

Internet Explorer対応の終了

htmx 2.0はInternet Explorerのsupportを終了しました。 これにより古いbrowser向けの互換処理がcoreから削除されています。

「ファイルサイズが必ず何KB減る」「画面が何ms速くなる」とは断定できません。 配信方法、HTML、server応答を含む実際の環境で計測します。

extensionをcoreから分離

Server-Sent Events（SSE）やWebSocketなどのextensionは、htmx本体とは別のrepositoryと配布先へ移りました。

1.xで使っていたhx-sseとhx-wsは削除され、2.0ではSSE extension、WebSocket extensionを使います。 古いURLをcopyせず、公式extension一覧から現在の導入方法を確認してください。

本体だけを2.0へ更新すると、古いextensionが動かなくなる場合があります。 本体とextensionを一緒に検証します。

htmx 1.xから2.xへの移行でCoreから分離されたSSEとWebSocket Extensionを、本体と一緒に更新・Testする図

DELETE requestのparameter送信

htmx 2.0では、DELETE requestのparameterをrequest bodyではなくURL parameterとして送ります。 serverがDELETE bodyを読んでいた場合は、request parsingとroute testを見直してください。

必要な場合はcompatibility configurationで以前の挙動へ戻せますが、移行後の送信形式を明示する方が保守しやすくなります。

module向け配布形式

ESM、AMD、CommonJS向けのdistribution fileが追加されました。 script tagで読み込む既存構成を、必ずmoduleへ変更する必要はありません。

bundlerを利用する場合は、採用する配布形式とextensionの読み込み方法を揃えます。

非推奨だったevent属性の整理

旧形式のhx-on属性は削除され、event名を属性名に含めるhx-on:形式を使います。

<button hx-on:click="console.log('clicked')">
  確認
</button>

既存属性を2.0で初めて追加された機能として扱わないよう、release noteで導入時期を確認してください。

default設定の変更

2.0では、いくつかのdefault configurationが変わりました。

  • selfRequestsOnlyが既定で有効
  • scrollBehaviorの既定値がinstant

別originへhtmx requestを送っていた画面は、selfRequestsOnlyの影響を確認します。 scrollの見え方に依存するUIも回帰testが必要です。

Web Componentsとswap API

Web Componentsとの連携が改善され、shadow root内の処理が見直されました。 また、swap処理を利用するためのpublic APIが追加されています。

独自elementや独自extensionを持つprojectほど、内部APIへの依存がないか確認してください。

1.xからの移行checklist

  1. 現在のhtmxとextensionのversionを固定して記録する
  2. 公式migration guideで削除・default変更を確認する
  3. hx-sseとhx-wsを新しいextensionへ移す
  4. extensionの古い配布URLを現在のものへ変更する
  5. DELETE parameterをserverが正しく受け取るかtestする
  6. hx-onの旧形式をhx-on:へ変更する
  7. cross-origin requestとselfRequestsOnlyを確認する
  8. scroll、focus、history、swapの回帰testを行う
  9. error responseとtimeout時の表示を確認する

段階的に更新し、本体、extension、server側の変更を同時に混ぜすぎないようにします。

serverが返すHTMLには、利用者入力をそのまま連結しないでください。 HTML escapeと認可はhtmxが自動で代行するものではありません。

2026年時点の読み方

これは2024年に公開された2.0のrelease記録です。 2026年7月25日時点の実装では、version固定例や第三者の記事をそのまま使わず、公式docsと現在利用するversionのrelease情報を確認してください。

基本的なrequest、target、swap、security、accessibilityは、更新を集約しているhtmxの基本で説明しています。

参考リソース

おすすめ記事

← 一覧に戻る
PR
PR
PR
PR