HN 日本語サマリー

← 一覧へ戻る
Web開発

GoでHTMXをどのように使用するか

How I use HTMX with Go (alexedwards.net)

292 pointsby gnabgib92 コメント

要約

この記事では、Go言語でWebアプリケーションにインタラクティブ性を追加するためにHTMXを使用する方法について解説しています。サーバーサイドHTMLレンダリングの利点を維持しつつ、JavaScriptの記述量を最小限に抑え、スムーズなアプリのような操作感を実現するパターンを紹介しています。テンプレートの構造化、部分/全ページHTMLレスポンスの送信、リダイレクトとエラー処理、HTMXの設定について、具体的なプロジェクト例を交えて説明します。

全文翻訳

GoでHTMXを使う方法

Webアプリケーションにインタラクティブ性を少しだけ加えたいとき、私はHTMXを使うのが大好きです。インタラクションにスムーズなアプリのような感触を与えやすく、書かなければならないJavaScriptの量を最小限に抑えられ、Goのhtml/templateパッケージを使ったサーバーサイドHTMLレンダリングの一貫性と安全性を維持できるからです。

この記事では、私が通常どのようにHTMXをGoと組み合わせて使用するかを説明します。HTMXの仕組みについても少し触れますが、主な焦点はGo側のことになります。具体的には以下の点です。

  • HTMXに部分ページおよび完全ページHTML応答を送信するためのHTMLテンプレートの構造化パターン
  • HTMX使用時のリダイレクトとエラーの管理
  • 私が使用する標準的なHTMX設定とその理由

これらの点を説明するために、最終的に以下のようなユーザーリストのフィルタリングを実装する小さなアプリケーションの構築を進めていきます。

[動画: ユーザーリストのフィルタリングデモ]

プロジェクトのセットアップ

もし一緒に進めたい場合は、以下のコマンドを実行してプロジェクトのスケルトン構造を作成してください。

$ go mod init example.com/htmx
$ mkdir -p assets/static/css assets/static/img assets/static/js assets/html/partials assets/html/pages
$ mkdir cmd/web
$ touch assets/efs.go assets/html/base.tmpl assets/html/partials/images.tmpl assets/html/pages/home.tmpl cmd/web/main.go cmd/web/handlers.go cmd/web/html.go

これにより、以下のようなファイルツリーが得られるはずです。

.
├── assets
│   ├── efs.go
│   ├── html
│   │   ├── base.tmpl
│   │   ├── pages
│   │   │   └── home.tmpl
│   │   └── partials
│   │       └── images.tmpl
│   └── static
│       ├── css
│       ├── img
│       └── js
├── cmd
│   └── web
│       ├── handlers.go
│       ├── html.go
│       └── main.go
└── go.mod

HTMXのインストール

HTMXをインストールする方法はいくつかありますが、CDNから読み込んだりNPMを使ったりすることもできます。しかし、私はほとんどの場合コピーをダウンロードして、Webアプリケーションから静的ファイルとして提供しています。これはシンプルで、CDNを使用するデメリットを回避できます。

このデモプロジェクトでは、Bamboo(クラスレスCSSフレームワーク)と、github.com/egonelbre/gophersからゴファーの画像もダウンロードします。以下のコマンドを実行して、これら3つすべてをassets/staticフォルダにダウンロードしてください。

$ wget -P assets/static/js https://cdn.jsdelivr.net/npm/htmx.org@1.9.10/dist/htmx.min.js
$ wget -P assets/static/css https://cdn.jsdelivr.net/npm/bamboo.css@1.0.2/dist/bamboo.min.css
$ wget -O assets/static/img/gopher.png https://raw.githubusercontent.com/egonelbre/gophers/refs/heads/master/sketch/misc/standing-left.png

これでassets/staticの内容は以下のようになります。

assets/static
├── css
│   └── bamboo.min.css
├── img
│   └── gopher.png
└── js
    └── htmx.min.js

HTMLテンプレート

さて、プロジェクトのスケルトンと静的アセットが配置されたので、この記事の主要な部分であるHTMLテンプレートについて話しましょう。

ほとんどすべてのプロジェクトで、私の出発点はassets/htmlディレクトリで、以下のようなフォルダ構造になっています。

assets/html
├── base.tmpl
├── pages
│   └── home.tmpl
└── partials
    └── images.tmpl

この構造の下では:

  • assets/html/base.tmplファイルには、すべてのWebページの共通HTML「レイアウト」マークアップが含まれています。
  • assets/html/pagesディレクトリのファイルには、個々のWebページに固有のコンテンツが含まれています。
  • assets/html/partialsディレクトリのファイルには、さまざまな場所で使用できる再利用可能なHTMLマークアップのチャンクが含まれています。

もし一緒に進めているなら、base.tmplファイルに以下のマークアップを追加してください。

ファイル: assets/html/base.tmpl

{{define "base"}}
<!doctype html>
<html lang='en'>
    <head>
        <meta charset='utf-8'>
        <title>{{template "page:title" .}}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <link rel="stylesheet" href="/static/css/bamboo.min.css">
        <script defer src="/static/js/htmx.min.js"></script>
    </head>
    <body>
        <h1><a href="/">Example website</a></h1>
        <main>
            {{template "page:content" .}}
        </main>
    </body>
</html>
{{end}}

これについていくつか指摘しておきます。

  • <head>セクションでは、Bamboo CSSファイルとHTMX JavaScriptファイルをインポートしています。HTMXをインポートする際にはdefer属性を使用していることに注意してください。これは、HTMXがWebページのHTMLを解析するのと並行してブラウザによって取得されますが、スクリプトはHTMLが完全に解析されてDOMが構築されるまで実行されないことを意味します。deferがどのように機能し、なぜそれが正しい選択であるかを説明する優れたブログ記事がここにあります。
  • HTMLテンプレートを書くとき、私はすべてのテンプレートに明示的な名前を付けるのが好きです。たとえ(この例のように)ファイルに1つのテンプレートしか含まれておらず、それが厳密には必要ない場合でも、{{define}}...{{end}}アクションでマークアップを囲みます。あなたのやり方とは異なるかもしれませんが、私はGoコードから定義済みの名前とファイル名の混合を使用するのではなく、常に定義済みの名前でテンプレートを参照できる一貫性と明瞭さを好みます。
  • テンプレート内では、{{template "page:title" .}}のようなアクションを使用して、適切なページ固有のコンテンツを正しい場所に注入します。

さて、ホームページのページ固有のコンテンツをassets/html/pages/home.tmplファイルに追加しましょう。

ファイル: assets/html/pages/home.tmpl

{{define "page:title"}}Home{{end}}

{{define "page:content"}}
<button hx-get="/gopher" hx-swap="outerHTML"> Wanna see a cute gopher? </button>
{{end}}

このページには、2つのHTMX属性を持つ<button>があります:hx-get="/gopher"とhx-swap="outerHTML"です。これは、このボタンがクリックされると、HTMXがクリックをインターセプトし、アプリケーションにGET /gopherリクエストを送信し、その後アプリケーションが返すHTMLでDOMのボタンを置き換えることを意味します。

最後に、ダウンロードしたゴファー画像を表示するためのHTMLを含むテンプレートをassets/html/partials/images.tmplに追加しましょう。

ファイル: assets/html/partials/images.tmpl

{{define "partial:image:gopher"}}
<img alt="Gopher" src="/static/img/gopher.png" width="{{.}}">
{{end}}

このマークアップではwidth="{{.}}"を使用していることに注意してください。これにより、画像幅の動的な値をテンプレートに渡すことができます。

アセットの埋め込み

Go 1.16でファイル埋め込みが導入されて以来、私は通常、HTMLファイルと静的アセットをランタイムでディスクから読み取るのではなく、Goバイナリに埋め込んでいます。

assets/efs.goファイルを更新して、assets/htmlおよびassets/staticディレクトリの内容を埋め込み、それらをHTMLFilesおよびStaticFilesという2つのグローバル変数で利用できるようにしましょう。以下のようになります。

ファイル: assets/efs.go

package assets

import (
	"embed"
	"io/fs"
)

//go:embed "html" "static"
var files embed.FS

var (
	HTMLFiles   = sub(files, "html")
	StaticFiles = sub(files, "static")
)

func sub(f embed.FS, dir string) fs.FS {
	sub, err := fs.Sub(f, dir)
	if err != nil {
		panic(err)
	}
	return sub
}

このコードでは、//go:embed "html" "static"ディレクティブがassets/htmlおよびassets/staticディレクトリの内容をfiles変数(assetsディレクトリをルートとするembed.FS)に埋め込みます。

その後、小さなsub()関数を使用して、htmlおよびstaticディレクトリをルートとする2つのサブファイルシステムを作成し、それぞれHTMLFilesおよびStaticFiles変数に割り当てました。これにより、2つの利点があります。

  • Goコードで使用する際に、静的ファイルとHTMLファイルを明確に分離できます。静的ファイルのみを操作することを意図したコードは、HTMLファイルへの不要なアクセスを持たず、その逆も同様です。
  • HTMLFilesおよびStaticFilesファイルシステムを使用するコードは、ファイルを開く際にhtml/またはstatic/パスプレフィックスを含める必要がありません。

HTMLテンプレートのレンダリング

HTTPレスポンスでHTMLテンプレートをレンダリングするために、NiceなパターンはhtmlRenderer型を作成することです。この型は、a) 起動時に共有テンプレートのセットを解析し、b) 共有テンプレートセットをクローンして拡張してから、特定の名前付きテンプレートを実行してHTTPレスポンスとして送信するrender()メソッドを持ちます。

cmd/web/html.goファイルに以下のhtmlRenderer型を作成してください。

ファイル: cmd/web/html.go

package main

import (
	"bytes"
	"html/template"
	"io/fs"
	"net/http"
	"time"
)

type htmlRenderer struct {
	templateFS      fs.FS
	sharedTemplates *template.Template
}

// newHTMLRenderer関数は、カスタムテンプレート関数をサポートする共有解析済みテンプレートのセットを含む新しいhtmlRendererを作成します。
func newHTMLRenderer(templateFS fs.FS, sharedTemplateFiles ...string) (*htmlRenderer, error) {
	funcs := template.FuncMap{
		"now": time.Now,
		// その他のカスタムテンプレート関数はここに追加...
	}

	sharedTemplates, err := template.New("").Funcs(funcs).ParseFS(templateFS, sharedTemplateFiles...)
	if err != nil {
		return nil, err
	}

	r := &htmlRenderer{
		templateFS:      templateFS,
		sharedTemplates: sharedTemplates,
	}

	return r, nil
}

// renderメソッドは共有テンプレートセットをクローンし、オプションで追加のテンプレートを解析し、指定されたデータで名前付きテンプレートを実行し、レスポンスを書き込みます。
func (h *htmlRenderer) render(w http.ResponseWriter, status int, data any, templateName string, additionalTemplateFiles ...string) error {
	ts, err := h.sharedTemplates.Clone()
	if err != nil {
		return err
	}

	if len(additionalTemplateFiles) > 0 {
		ts, err = ts.ParseFS(h.templateFS, additionalTemplateFiles...)
		if err != nil {
			return err
		}
	}

	buf := new(bytes.Buffer)

	err = ts.ExecuteTemplate(buf, templateName, data)
	if err != nil {
		return err
	}

	w.WriteHeader(status)
	buf.WriteTo(w)

	return nil
}

そして、cmd/web/main.goファイルで、基本的なWebアプリケーションを以下のように作成しましょう。

ファイル: cmd/web/main.go

package main

import (
	"log/slog"
	"net/http"
	"os"

	"example.com/htmx/assets"
)

// application構造体は、htmlRendererを含むハンドラに必要な依存関係を保持します。
type application struct {
	logger *slog.Logger
	html   *htmlRenderer
}

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

	// newHTMLRendererを初期化し、ベーステンプレートとassets/htmlからのすべての部分テンプレートを共有テンプレートセットに解析します。
	htmlRenderer, err := newHTMLRenderer(assets.HTMLFiles, "base.tmpl", "partials/*.tmpl")
	if err != nil {
		logger.Error(err.Error())
		os.Exit(1)
	}

	// htmlRendererをapplication構造体に含めます。
	app := &application{
		logger: logger,
		html:   htmlRenderer,
	}

	// assets/staticからファイルをサーブするファイルサーバーを作成します。
	fileserver := http.FileServerFS(assets.StaticFiles)

	// applicationのルートを登録します。
	mux := http.NewServeMux()
	mux.Handle("GET /static/", http.StripPrefix("/static", fileserver))
	mux.HandleFunc("GET /{$}", app.home)

	// HTTPサーバーを起動します。
	logger.Info("starting server", "port", 5051)
	err = http.ListenAndServe(":5051", mux)
	if err != nil {
		logger.Error(err.Error())
		os.Exit(1)
	}
}

この記事にとって重要で関連性の高いのは、newHTMLRenderer()への初期化呼び出しです。この呼び出しでは、"base.tmpl"と"partials/*.tmpl"というグロブパスを渡します。これは、ベーステンプレートとpartialsディレクトリ内のすべてのテンプレートが共有テンプレートセットで利用可能になることを意味します。

それが配置されたら、cmd/web/handlers.goでhomeハンドラのコードを以下のように記述できます。

ファイル: cmd/web/handlers.go

package main

import (
	"net/http"
)

func (app *application) home(w http.ResponseWriter, r *http.Request) {
	err := app.html.render(w, 200, nil, "base", "pages/home.tmpl")
	if err != nil {
		app.logger.Error(err.Error())
		http.Error(w, http.StatusText(500), 500)
	}
}

上記のコードでrender()を呼び出すとき、私たちは実質的にpages/home.tmplのテンプレートを共有テンプレートセットに追加し、その後baseテンプレートを200 OKステータスとともにレンダリングすることを意味します。

これで、アプリケーションを正常に実行できるようになるはずです。

$ go run ./...
time=2026-06-27T21:05:01.668+02:00 level=INFO msg="starting server" port=5051

そして、ブラウザでhttp://localhost:5051にアクセスすると、ホームページが以下のように表示されるはずです。

[画像: ホームページが表示されているスクリーンショット]

パーシャル(部分テンプレート)のレンダリング

このホームページにいる間に、開発者ツールを開いて「Wanna see a cute gopher?」ボタンをクリックすると、GET /gopherリクエストが送信されて404エラーになることがわかります。これを修正して、アプリケーションにGET /gopherルートを含め、partial:image:gopherテンプレートの内容を返すようにしましょう。

まず、新しいルートを追加します。

ファイル: cmd/web/main.go

package main

...

func main() {
	...

	mux := http.NewServeMux()
	mux.Handle("GET /static/", http.StripPrefix("/static", fileserver))
	mux.HandleFunc("GET /{$}", app.home)
	mux.HandleFunc("GET /gopher", app.gopher)

	...
}

そして、cmd/web/handlers.goで、partial:image:gopherテンプレートを幅100pxでレンダリングする新しいgopher()ハンドラを作成します。

ファイル: cmd/web/handlers.go

package main

...

func (app *application) gopher(w http.ResponseWriter, r *http.Request) {
	width := 100
	err := app.html.render(w, http.StatusOK, width, "partial:image:gopher")
	if err != nil {
		app.logger.Error(err.Error())
		http.Error(w, http.StatusText(500), 500)
	}
}

htmlRenderer型を、共有テンプレートセットにすでにすべてのパーシャルが含まれるように設定したため、追加のファイルパスを渡さずにrender()をこのように呼び出すだけで十分です。

アプリケーションを再実行してボタンをクリックすると、ゴファー画像に置き換えられるはずです。

[動画: ゴファー画像が表示されるデモ]

このように、ここまで来るのに時間がかかりましたが、現在確立されているパターンは洗練されており、いくつかの利点があります。

  • テンプレート(および静的アセット)はGoバイナリに埋め込まれるため、配布とデプロイが容易になります。
  • 同じhtmlRenderer.render()関数を使用して、完全なHTMLページまたは特定のパーシャルをクライアントに送信できるため、HTMXが必要なときに部分応答を簡単に送信できます。
  • ベーステンプレートとパーシャルを使用することで、HTMLマークアップをきれいにDRY(Don't Repeat Yourself)に保つことができます。パーシャルは、ベーステンプレート、ページ固有のコンテンツ、または他のパーシャルに挿入できます。

より複雑な例

これはインタラクティブ性の点では非常に基本的だったので、もう少し現実的なことをして、HTMXウェブサイトのアクティブ検索例を模倣した「ユーザー検索」ページを作成しましょう。

これを機能させるために、アプリケーションに2つの新しいルートを作成します。

  • GET /usersルート:すべてのユーザーの詳細のテーブルを含む完全なHTMLページを返します。
  • GET /users/searchルート:名またはメールが特定の検索値と一致するユーザーのみのテーブル行を含むHTMLパーシャルを返します。

これで、すべての基盤が整ったので、作業は非常に迅速に進むはずです。

まず、ページ固有のHTMLコンテンツを含むassets/html/pages/users.tmplファイルを作成しましょう。

$ touch assets/html/pages/users.tmpl

ファイル: assets/html/pages/users.tmpl

{{define "page:title"}}Users{{end}}

{{define "page:content"}}
<input type="search" name="query"
       placeholder="Begin Typing To Search Users..."
       hx-get="/users/search"
       hx-trigger="input changed delay:500ms, keyup[key=='Enter']"
       hx-target="#search-results"
       hx-push-url="true">

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Email</th>
            <th>&nbsp;</th>
        </tr>
    </thead>
    <tbody id="search-results">
        {{template "users:rows" .}}
    </tbody>
</table>
{{end}}

<!-- Fragments for the users page -->

{{define "users:rows"}}
    {{range .}}
    <tr>
        <td>{{ .Name }}</td>
        <td>{{ .Email }}</td>
        <td>
            {{if .IsGopher}}
                {{template "partial:image:gopher" 24}}
            {{end}}
        </td>
    </tr>
    {{end}}
{{end}}

ここにはいくつか興味深い点があります。

最初の点は、<input>コントロールのHTMX属性です。ユーザーが入力フィールドにタイプすると、500ミリ秒の遅延の後(またはEnterキーを押した場合は即座に)、HTMXは検索語をクエリ文字列GET /users/search?query=fooとして含むリクエストを送信するように設定しました。応答を受信すると、HTMXは応答を<tbody id="search-results">要素の内部HTMLにスワップします。このプロジェクトでのデモンストレーション目的で、hx-push-url="true"属性も使用しています。これにより、HTMXがリクエストを行うたびにブラウザのURLバーが更新され、ブラウザの履歴に新しいエントリが追加されます。

また、テーブルの行をpage:contentテンプレートの一部としてではなく、独自のusers:rowsテンプレートでレンダリングするようにファイルを構造化しました。これをGET /users/searchで使用して、HTMXがスワップするための一致するユーザーテーブル行のみをレンダリングします。

次に、main.goで2つの新しいルートを設定しましょう。

ファイル: cmd/web/main.go

package main

...

func main() {
	...

	mux := http.NewServeMux()
	mux.Handle("GET /static/", http.StripPrefix("/static", fileserver))
	mux.HandleFunc("GET /{$}", app.home)
	mux.HandleFunc("GET /gopher", app.gopher)
	mux.HandleFunc("GET /users", app.listUsers)
	mux.HandleFunc("GET /users/search", app.searchUsers)

	...
}

そして最後に、handlers.goファイルに移動して、ハードコードされたユーザー詳細のリストと、2つの新しいハンドラlistUsersおよびsearchUsersを作成しましょう。

ファイル: cmd/web/handlers.go

package main

import (
	"net/http"
	"strings"
)

...

// user型を定義します。フィールドはHTMLテンプレートで参照できるようにエクスポートする必要があります。
type user struct {
	Name     string
	Email    string
	IsGopher bool
}

// ハードコードされたユーザーリストを作成します。
var users = []user{
	{"Alice Madsen", "[email protected]", true},
	{"Theo Thatcher", "[email protected]", true},
	{"Maxwell Albright", "[email protected]", false},
	{"Ruby Thompson", "[email protected]", false},
	{"Leona Rowan", "[email protected]", false},
	{"Alicia Lennox", "[email protected]", true},
	{"Ruben Mason", "[email protected]", false},
	{"Leo Reynolds", "[email protected]", false},
	{"Max Lester", "[email protected]", true},
	{"Theodore Allister", "[email protected]", false},
}

func (app *application) listUsers(w http.ResponseWriter, r *http.Request) {
	// "pages/users.tmpl"からのコンテンツとすべてのユーザー詳細を含む完全なHTMLページをレンダリングします。

	err := app.html.render(w, 200, users, "base", "pages/users.tmpl")
	if err != nil {
		app.logger.Error(err.Error())
		http.Error(w, http.StatusText(500), 500)
	}
}

func (app *application) searchUsers(w http.ResponseWriter, r *http.Request) {
	// クエリに一致するユーザーのリストをフィルタリングします。

	query := r.FormValue("query")

	var matches []user
	if query == "" {
		matches = users
	} else {
		for _, u := range users {
			if strings.Contains(u.Name, query) || strings.Contains(u.Email, query) {
				matches = append(matches, u)
			}
		}
	}

	// "pages/users.tmpl"ファイルから"users:rows"テンプレートのみを
	// 一致するユーザー詳細でレンダリングします。
	err := app.html.render(w, 200, matches, "users:rows", "pages/users.tmpl")
	if err != nil {
		app.logger.Error(err.Error())
		http.Error(w, http.StatusText(500), 500)
	}
}

テンプレートレンダリングに関しては、これらの新しいハンドラの両方でpages/users.tmplファイルからのテンプレートを共有テンプレートセットに追加していますが、listUsersではbaseテンプレートを実行し、searchUsersではusers:rowsテンプレートのみを実行します。

pages/users.tmplファイルでマークアップをどのように構造化し、テンプレートをどのように定義したかを少し考えるだけで、完全なHTMLドキュメントまたはHTMXが機能するために必要な適切なHTMLフラグメントのどちらかを送信するのは簡単です。

必要であれば、http://localhost:5051/usersにアクセスして試してみてください。タイプするにつれてリストがフィルタリングされるはずです。

[動画: ユーザー検索のフィルタリングデモ]

リクエストがHTMXから来ているかどうかの確認

これらはすべてうまく機能しますが、誰かがhttp://localhost:5051/users/search?query=leoのようなリンクを直接訪問したらどうなるでしょうか? または、それを共有したら? このようなリンクに直接アクセスした人は、ブラウザで部分的なHTML応答しか見ることができません。以下のような状態です。

[画像: 検索結果のパーシャルHTMLのみが表示されているスクリーンショット]

これは明らかに理想的ではありません。より良いアプローチは、リクエストがHTMXから来ているかどうかに応じて、searchUsersハンドラが送信する応答を変更することです。具体的には:

  • リクエストがHTMXから来ている場合、テーブルにスワップできるHTMLパーシャルを返すべきです。これはすでにやっていることと同じです。
  • リクエストがHTMXから来ていない場合、一致するユーザー詳細を含む完全なHTMLページを返す必要があります。

すでにHTMXを使用したことがあるならご存知かもしれませんが、HTMXからのリクエストには常にHX-Request: trueヘッダーが含まれています。したがって、必要なのは、そのヘッダーの存在を確認し、適切な応答を返すことだけです。これを支援するために、私は通常、小さなisHTMXRequest()関数を作成し、以下のように使用します。

ファイル: cmd/web/handlers.go

package main

...

func isHTMXRequest(r *http.Request) bool {
	return r.Header.Get("HX-Request") == "true"
}

func (app *application) searchUsers(w http.ResponseWriter, r *http.Request) {
	query := r.FormValue("query")

	var matches []user
	if query == "" {
		matches = users
	} else {
		for _, u := range users {
			if strings.Contains(u.Name, query) || strings.Contains(u.Email, query) {
				matches = append(matches, u)
			}
		}
	}

	// デフォルトではベーステンプレートをレンダリングします。
	template := "base"

	// ただし、リクエストがHTMXから来ている場合は、代わりにusers:rowsテンプレートをレンダリングします。
	if isHTMXRequest(r) {
		template = "users:rows"
	}

	err := app.html.render(w, 200, matches, template, "pages/users.tmpl")
	if err != nil {
		app.logger.Error(err.Error())
		http.Error(w, http.StatusText(500), 500)
	}
}

アプリケーションを再起動して、http://localhost:5051/users/search?query=leoに再度アクセスすると、一致するユーザーレコードのみを含む完全なHTMLページが表示されるはずです。

[画像: 検索結果が完全なHTMLページとして表示されているスクリーンショット]

しかし、これを完了するためにさらにいくつか行う必要があります。

searchUsersからHX-Requestヘッダーの値に基づいて異なる応答を送信しているため、キャッシュがサーバーとクライアントの間にある場合に、応答がこのヘッダーの値によって異なることを伝えるために、応答にVary: HX-Requestを設定する必要があります。

searchUsersでVary: HX-Requestヘッダーを設定することもできますが、render()関数ですべての応答に常に設定する方が簡単だと思います。これにより、すべての応答(homeハンドラやlistUsersからの応答を含む)にVaryヘッダーが設定されることになります。これは厳密には必要ではなく、少し無駄ですが、個々のハンドラでVaryヘッダーを正しく設定することを覚えておく必要がなくなり、それを忘れることによるバグのリスクを回避できるため、その価値はあると思います。

ファイル: cmd/web/html.go

func (h *htmlRenderer) render(w http.ResponseWriter, status int, data any, templateName string, additionalFiles ...string) error {
	...

	w.Header().Add("Vary", "HX-Request")
	w.WriteHeader(status)
	buf.WriteTo(w)

	return nil
}

バックボタンの動作

最後に、バックボタンの動作を考慮する必要があります。

HTMXがブラウザの履歴にエントリを追加するたびに(hx-push-urlまたはhx-boost属性を使用した場合)、ブラウザのローカルストレージに完全なページのHTMLをキャッシュします。ユーザーがバックボタンをクリックすると、この完全にキャッシュされたHTMLページが再表示されます。

デフォルトでは、HTMXキャッシュは最大10ページを保存します。キャッシュミスが発生した場合(つまり、ユーザーがキャッシュに一致するページがなくなるまで十分に後ろに移動した場合)、HTMXはサーバーにリクエストを再送信してそのURLのコンテンツを再取得します。

問題は、このリクエストにHX-Request: trueヘッダーが含まれることで、アプリケーションは完全なHTMLページではなく、部分的なHTML応答を返すことです。ユーザーはそれを再表示する必要があります。

このシナリオに対処するために、historyRestoreAsHxRequest設定があります。これは、キャッシュミスが原因でリクエストを送信する際にHTMXがHX-Request: trueヘッダーを含めるかどうかを制御します。ドキュメントでは次のように推奨されています。

部分的な応答をオプションで返すためにHX-Requestヘッダーを使用する場合は、常に無効にする必要があります。

そこで、HTMXを設定してhistoryRestoreAsHxRequest設定がfalseになるようにしましょう。

HTMXの設定方法はいくつかありますが、私は通常、base.tmplファイル内のmetaタグで設定するのが好きです。

ファイル: assets/html/base.tmpl

{{define "base"}}
<!doctype html>
<html lang='en'>
    <head>
        <meta charset='utf-8'>
        <title>{{template "page:title" .}}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta
            name="htmx-config"
            content='{
                "historyRestoreAsHxRequest": false
            }'
        >

        <link rel="stylesheet" href="/static/css/bamboo.min.css">
        <script defer src="/static/js/htmx.min.js"></script>
    </head>
    <body>
        <h1><a href="/">Example website</a></h1>
        <main>
            {{template "page:content" .}}
        </main>
    </body>
</html>
{{end}}

この設定が完了したら、バックボタンを使用する際にキャッシュミスが発生した場合、HTMXはHX-Request: trueヘッダーなしでアプリケーションにリクエストを送信し、アプリケーションはユーザーに再表示するための完全なHTMLページを返します。

リダイレクトの管理

HTMXをアプリケーションで使用すると、通常3xxリダイレクトの必要性が減少します。たとえば、フォームを送信するときに、確認ページにリダイレクトする標準のPost/Redirect/Getパターンを使用する代わりに、ページにスワップできる成功メッセージを含むHTMLパーシャルを返すことがよくあります。

しかし、それでもHTMXからのフォーム送信後に完全に新しいページにリダイレクトしたい場合があります。一般的な例は、ログイン成功後にプロフィールページにリダイレクトすることです。

残念ながら、これを実現するには通常の3xx応答を送信するだけでは不十分です。問題の核心は、ブラウザが自動的に3xx応答をインターセプトしてフォローするため、HTMXが3xx応答にアクセスする前に、リダイレクト後の最終応答のみを見ることになることです。HTMXは、裏でリダイレクトが発生したことを知らないため、通常どおり返されたコンテンツをスワップするだけです。

代わりに、通常のredirectのように動作するものが必要な場合は、2xx応答とHX-Redirectヘッダーを送信する必要があります。

たとえば、応答ヘッダーHX-Redirect: /foo/barを含めると、HTMXはブラウザに/foo/barに移動するように指示し、フルページリロードをトリガーします。重要なのは、/foo/barへのリクエストにHX-Request: trueヘッダーが含まれないことです。

しかし、元のリクエストがHTMXから来ていない状況も処理する必要があります。特に、JavaScriptが無効になっている場合やHTMXが正しくロードされない場合でもアプリケーションが機能するようにプログレッシブエンハンスメントを使用している場合です。その場合、GoハンドラからHX-Redirectヘッダーと2xx応答ではなく、通常の3xx応答を送信するフォールバックを送信することが重要です。

これらをまとめると、私は通常、以前に作成したisHTMXRequest()関数を活用するredirect()ヘルパーを作成します。それは以下のようになります。

func redirect(w http.ResponseWriter, r *http.Request, url string, code int) {
	if isHTMXRequest(r) {
		w.Header().Set("HX-Redirect", url)
		w.WriteHeader(http.StatusNoContent)
		return
	}

	http.Redirect(w, r, url, code)
}

そして、たとえば、ログイン成功後に/profileページにリダイレクトしたいシナリオでは、Goハンドラで次のように使用します。

redirect(w, r, "/profile", http.StatusSeeOther)

前述したように、HX-Redirectを使用するとフルページリロードがトリガーされます。しかし、別のオプションがあります。HX-Locationヘッダーです。これは、HTMXにフルページリロードなしでリダイレクトの動作を模倣させます。HTMXは提供されたURLのHTMLを取得し、それをHTMLボディにスワップし、ブラウザの履歴に新しいエントリを追加します。重要なのは、HTMLを取得する際にHX-Request: trueヘッダーが使用されることです。

一見すると、HX-Locationを使用するとフルページリロードが発生しないため、アプリケーションはよりスムーズなSPAのような体験を提供できるため、好ましいように思えるかもしれません。しかし、リダイレクト先のルートがHX-Request: trueヘッダーを使用して条件付きでHTMLパーシャルを送信する場合、問題が発生します。ハンドラは、リクエストがHX-Locationリダイレクトに従うHTMXから来ているのか(この場合、完全なページ応答を送信すべき)、それとも「通常の」HTMXリクエストから来ているのか(この場合、パーシャルを返すべき)を判断する方法がありません。

残念ながら、履歴復元リクエストとは異なり、HTMXはリダイレクト時にHX-Request: trueヘッダーを無効にする設定を提供していません。

そのため、ほとんどの場合、HX-Redirectを使用し、フルページリロードのデメリットを受け入れる方が簡単で安全だと思います。

しかし…注意深くアプリケーションを構造化し、リダイレクト先のルートが常に完全なHTMLページのみを返すようにすれば、redirect()ヘルパーを次のようにHX-Locationを使用するように変更することもできます。

func redirect(w http.ResponseWriter, r *http.Request, url string, code int) {
	if isHTMXRequest(r) {
		w.Header().Set("HX-Location", url)
		w.WriteHeader(http.StatusNoContent)
		return
	}

	http.Redirect(w, r, url, code)
}

エラーの管理

デモアプリケーションが4xxまたは5xx応答を返した場合、デフォルトではHTMXは応答をスワップしません。代わりにDOMはそのまま残り、コンソールにエラーメッセージが記録されます。

これを実際に試すには、gopherハンドラを(存在しない)"partial:image:missing"テンプレートをレンダリングするように変更してみてください。これにより、アプリケーションはエラーを返し、500ステータスコードとプレーンテキストの"Internal Server Error"応答をクライアントに送信することになります。

ファイル: cmd/web/handlers.go

func (app *application) gopher(w http.ResponseWriter, r *http.Request) {
	err := app.html.render(w, http.StatusOK, 100, "partial:image:missing")
	if err != nil {
		app.logger.Error(err.Error())
		http.Error(w, http.StatusText(500), 500)
	}
}

アプリケーションを実行して「Wanna see a cute gopher?」ボタンをクリックすると、画面上では何も変化しませんが、開発者ツールのネットワークタブでは500応答とコンソールでの問題の記録が表示されるはずです。

[動画: エラーが発生し、コンソールにログが表示されるデモ]

ほとんどの場合、これは理想的ではありません。アプリケーションがエラーメッセージを返している場合、通常はユーザーにこのメッセージを実際に見てもらいたいと思います。操作が(少なくとも開発者ツールを開いていない限り)サイレントに失敗するのではなく。

また、ほとんどの場合、4xxまたは5xx応答からのエラーメッセージを、HTMXを使用していない場合と同じ方法でフルページHTMLとして表示したいと考えています。これは、通常のHTMXターゲットではなく、<body>要素にスワップすることで実現します。

唯一の例外は422 Unprocessable Contentステータスです。これは通常、検証エラーを含むフォームを返す際に使用します。この場合、HTMXには返されたコンテンツを通常の通りターゲット要素にスワップしてもらいたいと考えています。

幸いなことに、HTMXのresponseHandling設定を使用して、異なる応答コードに対して異なる動作を設定できます。私は通常、次のように設定します。

  • 204 No Content応答の場合、アクションは実行されず、DOMに変更は加えられません。
  • 422 Unprocessable Content応答の場合、HTMXは通常の通り応答コンテンツをターゲットにスワップします。
  • その他のすべての4xxおよび5xx応答の場合、HTMXは返されたコンテンツを<body>要素にスワップします。
  • その他の応答の場合、HTMXは通常の通り応答コンテンツをターゲットにスワップします。

そして、以前と同様に、通常はこのHTMX設定metaタグを介して設定します。

ファイル: assets/html/base.tmpl

{{define "base"}}
<!doctype html>
<html lang='en'>
    <head>
        <meta charset='utf-8'>
        <title>{{template "page:title" .}}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta
            name="htmx-config"
            content='{
                "historyRestoreAsHxRequest": false,
                "responseHandling":[
                    {"code":"204", "swap": false},
                    {"code":"422", "swap": true},
                    {"code":"[45]..", "swap": true, "target": "body"},
                    {"code":"...", "swap": true}
                ]
            }'
        >

        <link rel="stylesheet" href="/static/css/bamboo.min.css">
        <script defer src="/static/js/htmx.min.js"></script>
    </head>
    <body>
        <h1><a href="/">Example website</a></h1>
        <main>
            {{template "page:content" .}}
        </main>
    </body>
</html>
{{end}}

この変更を加えたら、アプリケーションを再起動してボタンをもう一度クリックすると、「Internal Server Error」メッセージがフルページ応答として表示されるはずです。

[動画: エラーメッセージがフルページとして表示されるデモ]

現在のブラウザURL

HTMXはAJAXリクエストを行い、ブラウザのURLを変更せずに(hx-boost、hx-push-url、またはhx-replace-url属性を使用しない限り)応答をスワップするため、r.URLにアクセスしたときにGoハンドラで見られるリクエストURLは、ユーザーがブラウザで見ているURLと異なる場合があります。

時々、ユーザーが現在ブラウザで見ているURLをGoハンドラで正確に知りたい場合があります。幸いなことに、HTMXは各リクエストにHX-Current-URLヘッダーでこの情報を含めて送信します。

通常、これに役立つ別の小さな関数を作成し、HX-Current-URL値を解析してurl.URLとして返します。HX-Current-URLヘッダーが存在しない場合は、r.URLを返すようにフォールバックします。以下のようになります。

func browserURL(r *http.Request) (*url.URL, error) {
	cu := r.Header.Get("HX-Current-URL")
	if cu != "" {
		return url.Parse(cu)
	}

	return r.URL, nil
}

追加のHTMX設定

最後に、デフォルト値から変更することが多い、他のいくつかのHTMX設定があります。

  • historyCacheSizeを0に設定して、HTMXキャッシュを完全に無効にする傾向があります。ローカルストレージでのページキャッシュは、バグやセキュリティ問題の原因となるため、完全に無効にする方がシンプルで良いと思います。これを実行すると、ローカルストレージにページはキャッシュされなくなり、ユーザーがバックボタンをクリックするとHTMXはHTMLを再取得するためにサーバーにリクエストを送信します。同じ理由で、将来のHTMXバージョンではローカルストレージでのキャッシュもデフォルトで無効になることに注意してください。

  • disableInheritanceをtrueに設定して、HTMXの属性継承を無効にすることをお勧めします。HTMX属性が常に明示的に宣言されている場合、より明確でバグや意図しない動作のリスクが低減すると考えられます。ここでも、将来のHTMXバージョンでは属性継承もデフォルトで無効になることに注意してください。

  • includeIndicatorStylesをfalseに設定して、HTMXのインジケーター(ローディング表示)スタイルを無効にします。一貫性のために、HTMXがスタイルを注入するのを避け、他のCSSルールと一緒にインジケータースタイルを定義したいと考えています。

  • デフォルトではHTMXリクエストにタイムアウトはなく、サーバーが応答するまで必要なだけ待機します。これはプロジェクト固有であり、Goアプリケーションでのタイムアウトやデッドラインの処理方法に依存しますが、場合によってはtimeout設定を使用してHTMX側でデフォルトのタイムアウト(ミリ秒単位)を設定することもあります。

全体として、私のHTMX設定の出発点は通常以下のようになります。

<meta
    name="htmx-config"
    content='{
        "includeIndicatorStyles": false,
        "historyCacheSize": 0,
        "historyRestoreAsHxRequest": false,
        "responseHandling":[
            {"code":"204", "swap": false},
            {"code":"422", "swap": true},
            {"code":"[45]..", "swap": true, "target": "body"},
            {"code":"...", "swap": true}
        ],
        "timeout": 5000
    }'
>

ページ固有のレイアウト

この記事を、大規模アプリケーションにおけるHTMLテンプレートに関する最後の注記で締めくくりましょう。

一部のアプリケーションでは、ベーステンプレートとページ固有のテンプレートだけでは不十分な場合があります。また、ベーステンプレートとページ固有のコンテンツの間に「レイアウト」テンプレートが必要になる場合もあります。たとえば、通常のアプリケーションページとは異なる、管理エリアページ用のレイアウトテンプレートを使用したい場合があります。

この記事で説明したパターンは、これを容易に拡張して対応できます。

たとえば、ベーステンプレートを変更して、ページ固有のコンテンツを直接挿入するのではなく、<body>要素に"layout"テンプレートを挿入するようにすることができます。

{{define "base"}}
<!doctype html>
<html lang='en'>
    <head>
        <meta charset='utf-8'>
        <title>{{template "page:title" .}}</title>

        ...
    </head>
    <body>
        {{template "layout" .}}
    </body>
</html>
{{end}}

次に、管理ページ用の共通の「レイアウト」マークアップを含むassets/html/layouts/admin.tmplファイルを作成できます。

{{define "layout"}}
<h1><a href="/">Admin area</a></h1>
<nav>
    <a href="/admin/users">Users</a>
    <a href="/admin/orders">Orders</a>
</nav>
<main>
    {{template "page:content" .}}
</main>
{{end}}

そして、Goハンドラでrender()呼び出しの一部として、使用したいレイアウトテンプレートを指定できます。以下のようになります。

func (app *application) adminOrders(w http.ResponseWriter, r *http.Request) {
	err := app.html.render(w, 200, nil, "base", "layouts/admin.tmpl", "pages/admin-orders.tmpl")
	if err != nil {
		app.logger.Error(err.Error())
		http.Error(w, http.StatusText(500), 500)
	}
}