HN 日本語サマリー

← 一覧へ戻る
Web開発

最悪のHtmxを作ろう

Let's make the worst Htmx (zserge.com)

108 pointsby RebelPotato35 コメント

要約

この記事は、人気のあるWebフレームワークのミニチュア版を構築するシリーズの一環として、HTMXの機能を模倣したシンプルなJavaScriptライブラリの作成について解説しています。HTMXの基本的な概念であるイベントトリガー、AJAXリクエスト、DOM更新(スワップ)を、少ないコード量で実現する方法を示しています。

全文翻訳

最悪のhtmxを作ろう!

これは、人気のウェブフレームワークの小さな「クローン」を構築する一連の投稿の続きです。

ウェブは急速に変化しており、ウェブアプリの構築に使用するツールも同様です(とはいえ、私のReact/Vueに関する投稿が7年前のもので、それらのフレームワークが今でも人気があり関連性があることを心から嬉しく思います)。

今日ホットなトピックはhtmxです。これは基本的に、JavaScriptに全く関心のないバックエンド開発者のためのフロントエンドライブラリです。HTMXはintercoolerとして始まり、その後進化してより多くの機能が追加され、そこにはある種の美しさがあります。

<button hx-post="/clicked"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="outerHTML">
    Click Me!
</button>

宣言的な方法で、これは次のように述べています:ボタンがクリックされたときに、/clickedにPOSTリクエストを送信し、#parent-div IDを持つ要素の外部HTMLをレスポンスデータで置き換えます。HTMXはイベント、AJAXリクエスト、DOM更新を連携させ、フロントエンドの複雑さを隠蔽します。バックエンドがHTMLテンプレートを送信できる限り、JavaScriptを一行も書かずに多くのことを達成し、完全なアプリを構築できます。

メソッド、トリガー、ターゲット、スワップ

上記の例を見ると、私たちのライブラリは、特定のトリガーに基づいていくつかのURLを取得し、ターゲット要素のコンテンツをスワップする必要があるようです。このような感じです:

<button x-get="/click">Click me</button>
document.querySelectorAll('[x-get]').forEach(el => {
    el.addEventListener('click', async (e) => {
        e.preventDefault();
        const url = el.getAttribute('x-get');
        const response = await fetch(url);
        const data = await response.text();
        el.outerHTML = data;
        console.log(data);
    });
});

バックエンドが「Button clicked」とレスポンスで送信する場合、これは機能するはずです。ページを開き、ボタンをクリックすると、ボタンが消え、代わりにテキストが表示されます。これが10行のコードでのHTMXです。

ここで改善できる点がいくつかあります。まず、レスポンスがHTMLであることを確認するために、レスポンスをサニタイズするのは良いことです。次に、ユーザーがコンテンツをスワップするターゲット要素を指定できるようにする必要があります。第三に、ターゲット内のコンテンツをどのようにスワップするかをユーザーが指定できるようにする必要があります:置換、追加、先頭に追加、要素の削除などです:

const attr = (el, name) => el.closest(`[${name}]`)?.getAttribute(name);

const SWAP = {
  outerHTML: (t, f) => t.replaceWith(f),
  beforebegin: (t, f) => t.before(f),
  afterbegin: (t, f) => t.prepend(f),
  beforeend: (t, f) => t.append(f),
  afterend: (t, f) => t.after(f),
  delete: t => t.remove(),
  none: () => {},
};

const swap = (mode, target, html) => {
  const tpl = document.createElement('template');
  tpl.innerHTML = html;
  (SWAP[mode] || ((t, f) => t.replaceChildren(f)))(target, tpl.content);
};

これで、さまざまなメソッド、トリガー、ターゲット、スワップモードを処理できる、より汎用的な「フェッチャー」関数を作成できます:

const send = async (el, method, url) => {
  const sel = attr(el, 'x-target');
  const target = sel ? document.querySelector(sel) : el;
  const mode = attr(el, 'x-swap') || 'innerHTML';
  const opts = { method: method.toUpperCase(), headers: { 'X-Request': 'true' } };
  if (el.matches('form')) opts.body = new URLSearchParams(new FormData(el));
  const res = await fetch(url, opts);
  swap(mode, target, await res.text());
};

デフォルトでは、x-targetまたはx-swapが指定されていない限り、要素のコンテンツを更新します。また、HTMXの慣習に従い、リクエストと共にカスタムヘッダーをバックエンドに送信します。これらすべてをまとめるために、トリガーに基づいてリクエストをディスパッチする簡単なイベントリスナーを追加します:

const METHODS = ['get', 'post', 'put', 'patch', 'delete'];

const defaultTrigger = el =>
  el.matches('form') ? 'submit' : el.matches('input,select,textarea') ? 'change' : 'click';

const scan = (root = document.body) =>
  METHODS.forEach(m =>
    root.querySelectorAll(`[x-${m}]`).forEach(el => {
      if (el.$hx) return;
      el.$hx = true;
      const evt = attr(el, 'x-trigger') || defaultTrigger(el);
      el.addEventListener(evt, e => {
        e.preventDefault();
        send(el, m, el.getAttribute(`hx-${m}`));
      });
    })
  );

scan();
// swap() の後に send() の中で scan() を呼び出す必要があります

これで完了です。40行のコードで、すべてのHTTPメソッド、カスタムターゲット、スワップ戦略をサポートする動作するHTMXクローンが得られます。小さな最適化として、各スワップ後にDOM全体を再スキャンするのを避け、新しく追加されたコンテンツのみをスキャンすることが挙げられます:

new MutationObserver(ms => {
  for (const m of ms) m.addedNodes.forEach(n => { if (n.nodeType === 1) scan(n); });
}).observe(document.body, { childList: true, subtree: true });

これで、小さくパフォーマンスも良くなりました。

より良いトリガー

カスタム構文のトリガーを導入し、イベントのカンマ区切りリスト、オプションの遅延、「changed」または「once」修飾子などを許可できます:

const parseTriggers = (s) => {
  const triggers = s.split(',').map(s => s.trim());
  return triggers.map(trigger => {
    const [event, ...rest] = trigger.split(' ');
    const options = {};
    rest.forEach(opt => {
      const [key, value = true] = opt.split(':');
      options[key] = value;
    });
    return { event, options };
  });
}

これは、オプション(HTML属性でコロンで区切られたキー/値)を持つイベントのリストを返します。これで、x-trigger="load, click one, change changed delay:500"のようなものを記述できます。また、scan()関数で一部のイベントを特別に処理する必要があります。例えば、loadは基本的にsetTimeout(() => send(...), 0)、changedは前の値をキャッシュし、値が変わらない場合は送信をスキップし、onceは最初のトリガー後にイベントリスナーを削除し、delayは指定された遅延で別のsetTimeoutです。あなたの想像力が限界です。HTMXが行ったように、ビューポートインタラクショントリガー、キューイング、デバウンス、周期的なイベントなどをサポートできます。しかし、ここでは悪いHTMXクローンを構築しています。

より良いターゲット

これまでは、コンテンツをスワップする要素を見つけるために単純なquerySelectorを使用しています。実際には、最も近い祖先や次の兄弟要素に一致するなど、さらにいくつかの修飾子をサポートしたい場合があります。

const resolve = (el, sel) => {
  if (!sel) return el;
  if (sel === 'this') return el;
  if (sel === 'next') return el.nextElementSibling;
  if (sel === 'previous') return el.previousElementSibling;
  if (sel === 'document') return document;
  if (sel === 'body') return document.body;
  if (sel === 'window') return window;
  if (sel.startsWith('closest ')) return el.closest(sel.slice(8));
  if (sel.startsWith('find ')) return el.querySelector(sel.slice(5));
  return document.querySelector(sel);
};

document.querySelector(sel)の代わりにsend()からこれを呼び出すと、グローバルクエリよりも具体的な要素をターゲットにするために、x-target="closest .container"やx-target="next"のようなものを記述できるようになります。HTMXも実際にはほぼ同じことを行っています。コードを検査したい場合は、それを見ることができます。

より良いイベント

HTMXはhtmx:beforeRequestのようなカスタムイベントを発行し、開発者がそれをインターセプトしてリクエストフローを変更・制御できるようにします。私たちも同様のことを行うことができます。合計で4つのイベントを発行します:beforeRequest、afterRequest、beforeSwap、afterSwap。各イベントはリクエストをトリガーした要素で、現在のsend()の完全なコンテキストと共に発行されます。イベントはevent.preventDefault()を呼び出すことでキャンセルできます。

サーバーサイドイベント、例えばHX-TriggerやHX-Redirectもサポートしてみましょう。サーバーがHX-Triggerヘッダーを送信した場合、そのヘッダーの内容を持つカスタムイベントをディスパッチします。サーバーがHX-Redirectを送信した場合、ブラウザをそのURLにリダイレクトするだけです。HXプレフィックスをここに保持したのは、X-...ヘッダーが標準HTTPヘッダーの一般的な規約であるためです。

const send = async (el, method, url) => {
  let target = resolve(el, attr(el, "x-target"));
  let mode = attr(el, "x-swap") || "innerHTML";
  const opts = {
    method: method.toUpperCase(),
    headers: { "HX-Request": "true" },
  };
  if (el.matches("form")) opts.body = new URLSearchParams(new FormData(el));
  if (!fire(el, "x:beforeSend", { el, url, target, mode, opts }, true))
    return;
  const response = await fetch(url, opts);
  const hdrTrigger = response.headers.get("HX-Trigger");
  if (hdrTrigger) {
    try {
      const data = JSON.parse(hdrTrigger);
      Object.entries(data).forEach(([ev, d]) => fire(document.body, ev, d));
    } catch {
      fire(document.body, hdrTrigger);
    }
  }
  if (response.headers.get("HX-Redirect")) {
    window.location.href = response.headers.get("HX-Redirect");
    return;
  }
  if (response.headers.get("HX-Refresh") === "true") {
    window.location.reload();
    return;
  }
  if (response.headers.get("HX-Retarget"))
    target = resolve(el, response.headers.get("HX-Retarget"));
  if (response.headers.get("HX-Reswap"))
    mode = response.headers.get("HX-Reswap");
  const html = await response.text();
  fire(el, "x:afterSend", { el, url, opts, target, mode, response, html });
  const detail = { el, url, target, mode, html, response };
  if (!fire(el, "x:beforeSwap", detail, true)) return;
  swap(detail.mode, detail.target, detail.html);
  fire(el, "x:afterSwap", detail);
  scan(detail.target); // rebind anything the swap just brought in
};

私たちの最終的なsend()は大きくなりましたが、リクエストやスワップをインターセプトすることでプラグインを作成できるようになります。イベントの詳細がどのように別のイベントに伝播するか、つまりイベントハンドラがリクエストとスワップの流れを変更できるかに注意してください。例えば、プラグインはx:beforeSwapをインターセプトし、条件や属性に基づいてターゲットやスワップモードを変更できます。

プラグイン

HTMXに関する私の最初の印象は、それがただ一つのことしかしないということでした。つまり、宣言的な設定を持つ要素でイベントが発生した場合、AJAXリクエストをURLに送信し、レスポンスを別の要素にスワップするということです。しかし、リファレンスを確認すると、hx-on、hx-vals、hx-headers、hx-swap-oob、hx-params、hx-push-url、hx-history-elt、hx-sse、hx-extなどの属性があり、理解が容易ではなくなっています。

コアの「ループ」を変更せずに、いくつかの機能を同等に達成できるでしょうか?そうすれば、「エッセンス」は「SSS」になるでしょう:scan + send + swap。

例えば、HTMXは「ブースティング」をサポートしています。これは、リンクやフォームをAJAXを使用するように強化し、フルページリロードを回避するものです(ナビゲーションリンクごとにx-getとx-targetを記述するのを避けるため)。これはプラグインである必要すらなく、単なるJavaScriptスニペットです:

document.addEventListener('click', e => {
  const boosted = e.target.closest('[x-boost]');
  if (!boosted) return;
  const link = e.target.closest('a');
  if (!link) return;
  const href = link.getAttribute('href');
  if (!href || href.startsWith('#') || link.getAttribute('target')) return;
  e.preventDefault();
  window.x.send(boosted, 'get', href);
});

同様に、送信時にフォームを「ブースト」できます。実装できるプラグインは他にもたくさんあります:

  • x-confirm — 送信する前にネイティブのconfirm()を表示し、キャンセルできるようにします。x:beforeSendリスナーが必要で、拒否した場合はe.preventDefault()。
  • x-indicator — リクエスト中にスピナーを表示します。x:beforeSendでクラス/スタイルを切り替え、x:afterSwapで元に戻す必要があります。
  • x-disable — リクエスト中は要素を無効にします(二重送信を回避)。インジケーターと同じロジックです。
  • x-headers — JSON属性からの追加リクエストヘッダー。x:beforeSendでopts.headersに解析してマージします。
  • x-vals / x-include — リクエストに値を追加します。x:beforeSendでopts.bodyをミューテートする必要があります。
  • x-select — 全体のHTMLではなく、レスポンスのフラグメントをスワップします(バックエンドコードをシンプルに保ちます)。x:beforeSwapでdetail.htmlを、その部分を使用するように変更します。querySelectorを使用します。
  • x-sync — 同時に実行されるリクエストは最大1つです。古いものを中止し、新しいものを使用するか、キューに入れます。ターゲットでキー付けされたマップ。
  • x-validate — 送信する前にブラウザのネイティブ制約検証を実行します。すべてx:beforeSendで完了します。
  • x-push-url / x-replace-url — 属性またはHX-Push-Url/HX-Replace-Urlヘッダーからブラウザ履歴を更新します。x:afterSwapでhistory.pushState/replaceStateが必要です。
  • x-sse / x-ws — レスポンスのようなストリーミングメッセージを使用し、そのコンテンツをスワップします。ここではリクエスト/レスポンスサイクルはまったくありません。単にonmessageからx.swap()を呼び出します。

これらのいずれもコアx.jsの変更を必要とせず、各プラグインは数十行のコードで、推論やデバッグが容易です。イベントベースのプラグインアーキテクチャと「SSS」APIは、私が期待していたよりも良く機能しているようです(そして、それでもhtmxより著しく小さいです)。

それでも、HTMXと完全に互換性を持たせるためには、コアにいくつかの追加作業が必要です。fetch()の失敗、2XX以外のレスポンスなどに対する適切なエラー処理が必要です。これには、おそらくさらに多くのカスタムイベントを発行する必要があります。また、プラグインがどこでも同じx-target構文を使用できるように、resolve()をプラグインに公開する必要があるでしょう。プロミスベースのキャンセルも必要です。明白なユースケースの1つは、非同期である必要があるカスタム確認ダイアログです。ビュー遷移も非同期である必要があり、プラグインは遷移が完了するまでスワップを遅延させることができます。おそらく、私が欠けているものがさらにあるでしょう。

これらは読者への演習として残されています。あるいは、htmxを使うこともできますか?

この実験の完全なコードはhttps://github.com/zserge/xにあります。バグを見つけたり、貢献したい場合は、ぜひそうしてください!

この記事を楽しんでいただけたなら幸いです。GitHub、Mastodon、Twitterでフォロー(および貢献)するか、rssで購読してください。

2026年7月27日

こちらも参照:Let's make the worst VueJS ever! および その他