From 03be483b919830d83f423edd254313dc75c774fd Mon Sep 17 00:00:00 2001 From: rameel Date: Tue, 3 Nov 2026 01:48:12 +0500 Subject: [PATCH] http: document that cross-origin requests need HX-Request-Type allowed With HTMX 1.9.x and 2.x, the Toolkit script adds HX-Request-Type to requests to other origins too. If such an origin lists its allowed headers explicitly, the browser blocks the request at the preflight, and an upgrade from 1.x does not reveal this at build time. Add a warning to the migration guide and mention it in troubleshooting. --- docs/articles/migrate-to-v2.md | 7 ++++++- docs/articles/troubleshooting.md | 4 ++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/articles/migrate-to-v2.md b/docs/articles/migrate-to-v2.md index cc1a2b4..3801b75 100644 --- a/docs/articles/migrate-to-v2.md +++ b/docs/articles/migrate-to-v2.md @@ -19,7 +19,7 @@ step; see [Version compatibility](version-compatibility.md) for that. | [Registration](#register-the-toolkit-and-select-the-htmx-version) | Call `AddHtmxToolkit()` and select the HTMX version; HTMX 2.x is the default | **Silent** | | [Global configuration](#move-global-configuration-to-code) | `` attributes move to `AddHtmxToolkit()` | **Silent** | | [Antiforgery](#antiforgery-metadata-is-on-by-default) | Metadata on by default, moved out of `htmx.config`; token sent to own origin only | **Silent** | -| [Toolkit script](#load-the-toolkit-script-as-a-static-asset) | Inline script helpers and `MapHtmxAntiforgeryScript` replaced by a static web asset | Build | +| [Toolkit script](#load-the-toolkit-script-as-a-static-asset) | Inline script helpers and `MapHtmxAntiforgeryScript` replaced by a static web asset | Build, **silent** | | [URL Tag Helper](#rename-the-url-tag-helper-attributes) | `hx-*` URL attributes become `asp-*`; `hx-host` and `hx-protocol` are removed | **Silent** | | [Requests](#update-request-handling) | `IsHtmxRequest()` is `false` for history restoration; `Boosted` filter renamed | Build, **silent** | | [Action result wrappers](#configure-responses-through-responsehtmx) | `IActionResult.Htmx(...)` removed | Build | @@ -208,6 +208,11 @@ In 2.0 it also sends `HX-Request-Type` for HTMX 1.9.x and 2.x, replays events wh and provides the `ramstack-swap` extension. See [What the Toolkit script does](antiforgery.md#what-the-toolkit-script-does) and [Static assets and deployment](static-assets.md). +> [!WARNING] +> The script also sends `HX-Request-Type` to other origins. If such an origin lists its allowed request headers explicitly, +> add `HX-Request-Type` to its `Access-Control-Allow-Headers`. Otherwise, the browser blocks the request at the preflight +> and HTMX raises `htmx:sendError`. + ## Rename the URL Tag Helper attributes The URL Tag Helper now reads the standard ASP.NET Core `asp-*` routing attributes instead of its own `hx-*` copies. diff --git a/docs/articles/troubleshooting.md b/docs/articles/troubleshooting.md index 40e800f..94db036 100644 --- a/docs/articles/troubleshooting.md +++ b/docs/articles/troubleshooting.md @@ -294,3 +294,7 @@ Configure application options at startup. Do not change these options while hand Client settings such as `SelfRequestsOnly`, `Mode`, `WithCredentials`, and per-request credentials do not configure server CORS. Check the browser CORS error, ASP.NET Core CORS policy, allowed origins, cookies, and credential rules together. + +The policy must allow every header that the request sends. With HTMX 1.9.x and 2.x, the Toolkit script adds +`HX-Request-Type` to the headers that HTMX sends, so include it in an explicit list of allowed headers. +Otherwise, the browser blocks the request at the preflight and HTMX raises `htmx:sendError`.