diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 26b1c3b04..d6076b542 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,10 +10,28 @@ jobs: test_suite: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Use Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: '20.x' - run: npm ci - run: npm test + codeql-scan: + name: CodeQL Security Scan + runs-on: ubuntu-22.04 + permissions: + security-events: write + actions: read + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: javascript + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index bf8f8e59b..fb74dfd69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,12 +1,13 @@ # Changelog -## [2.0.7] - 2025-10-24 +## [2.0.8] - 2025-10-24 * [Updated](https://github.com/bigskysoftware/htmx/commit/b9336a96fbdcf28550699971dc2218a90c7a4e01) `parseHTML` to use to use the (unfortunately named) [`Document.parseHTMLUnsafe()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/parseHTMLUnsafe_static) method for better Web Components support * [Added](https://github.com/bigskysoftware/htmx/commit/83a1449a89b1fcd1c1655039ede02d74d61e4800) `pushURL` option to the `htmx.ajax()` API * [Fixed](https://github.com/bigskysoftware/htmx/commit/cd045c3e0eb31776a80e3a4b4c74e37d0631c1f1) `hx-sync` and `htmx:abort` within the Shadow Dom [Issue 3419](https://github.com/bigskysoftware/htmx/issues/3419) * [Fixed](https://github.com/bigskysoftware/htmx/commit/04d6c7249b7fd7b8518ddca92e7a70fdcc651b34) a long-standing bug in history support with respect to relative paths [Issue 3449](https://github.com/bigskysoftware/htmx/issues/3449) +* Once again, this is a release mainly done by @MichaelWest22's heroic work, thank you! ## [2.0.7] - 2025-09-08 diff --git a/www/content/_index.md b/www/content/_index.md index 0c7675350..c300c7fa9 100644 --- a/www/content/_index.md +++ b/www/content/_index.md @@ -306,6 +306,11 @@ Thank you to all our generous +
+ + + +
ʕ •ᴥ•ʔ made in montana
diff --git a/www/content/docs.md b/www/content/docs.md index 3b0d22d7e..d8aaac86f 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -91,7 +91,7 @@ within the language: * Now any element, not just the entire window, can be the target for update by the request Note that when you are using htmx, on the server side you typically respond with *HTML*, not *JSON*. This keeps you firmly -within the [original web programming model](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm), +within the [original web programming model](https://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm), using [Hypertext As The Engine Of Application State](https://en.wikipedia.org/wiki/HATEOAS) without even needing to really understand that concept. @@ -101,7 +101,7 @@ It's worth mentioning that, if you prefer, you can use the [`data-`](https://htm Click Me! ``` -If you understand the concepts around htmx and want to see the quirks of the library, please see our +If you understand the concepts around htmx and want to see the quirks of the library, please see our [QUIRKS](@/QUIRKS.md) page. ## 1.x to 2.x Migration Guide @@ -1163,7 +1163,7 @@ If you are using a bundler to manage your javascript (e.g. Webpack, Rollup): - Import both packages to your `index.js` ```JS import `htmx.org`; -import `htmx-ext-extension-name`; // replace `extension-name` with the name of the extension +import `htmx-ext-extension-name`; // replace `extension-name` with the name of the extension ``` Note: [Idiomorph](/extensions/idiomorph) does not follow the naming convention of htmx extensions. Use `idiomorph` instead of `htmx-ext-idiomorph`. For example, `https://cdn.jsdelivr.net/npm/idiomorph` or `npm install idiomorph`. @@ -1379,7 +1379,7 @@ Here is an example of the code in action: ## Scripting {#scripting} -While htmx encourages a hypermedia approach to building web applications, it offers many options for client scripting. Scripting is included in the REST-ful description of web architecture, see: [Code-On-Demand](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_7). As much as is feasible, we recommend a [hypermedia-friendly](/essays/hypermedia-friendly-scripting) approach to scripting in your web application: +While htmx encourages a hypermedia approach to building web applications, it offers many options for client scripting. Scripting is included in the REST-ful description of web architecture, see: [Code-On-Demand](https://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm#sec_5_1_7). As much as is feasible, we recommend a [hypermedia-friendly](/essays/hypermedia-friendly-scripting) approach to scripting in your web application: * [Respect HATEOAS](/essays/hypermedia-friendly-scripting#prime_directive) * [Use events to communicate between components](/essays/hypermedia-friendly-scripting#events) @@ -1697,7 +1697,7 @@ for exploring this topic. ### CSRF Prevention -The assignment and checking of CSRF tokens are typically backend responsibilities, but `htmx` can support returning the CSRF token automatically with every request using the `hx-headers` attribute. The attribute needs to be added to the element issuing the request or one of its ancestor elements. This makes the `html` and `body` elements effective global vehicles for adding the CSRF token to the `HTTP` request header, as illustrated below. +The assignment and checking of CSRF tokens are typically backend responsibilities, but `htmx` can support returning the CSRF token automatically with every request using the `hx-headers` attribute. The attribute needs to be added to the element issuing the request or one of its ancestor elements. This makes the `html` and `body` elements effective global vehicles for adding the CSRF token to the `HTTP` request header, as illustrated below. Note: `hx-boost` does not update the `` or `` tags; if using this feature with `hx-boost`, make sure to include the CSRF token on an element that _will_ get replaced. Many web frameworks support automatically inserting the CSRF token as a hidden input in HTML forms. This is encouraged whenever possible. @@ -1713,7 +1713,7 @@ Note: `hx-boost` does not update the `` or `` tags; if using this fe ``` -The above elements are usually unique in an HTML document and should be easy to locate within templates. +The above elements are usually unique in an HTML document and should be easy to locate within templates. ## Configuring htmx {#config} diff --git a/www/content/essays/alternatives.md b/www/content/essays/alternatives.md index 4e2d6fa66..9388a7321 100644 --- a/www/content/essays/alternatives.md +++ b/www/content/essays/alternatives.md @@ -66,6 +66,12 @@ a single, tidy package that is smaller than htmx. You can see many examples of Datastar in action [here](https://data-star.dev/examples). +## Nomini + +[Nomini](https://github.com/nonnorm/nomini) is a hypermedia implementation that embraces writing JavaScript in the original and intended way, as a simple enhancement to mostly-static pages. Its goal is to add a minimal layer of LoB on top of HTML to allow for powerful server-driven web apps with easily implemented client-side features. Additionally, it is currently the smallest library existing that gives both reactive variables and partial page swaps (~2.8k minified, ~1.4k minzipped). + +In essence, Nomini is a tiny reimplementation of Datastar or a combination of Fixi and Alpine.js, intended to be a minimal, pragmatic building block for reactive server-driven UIs. + ## Alpine-ajax Speaking of Alpine (which is a common library to use in conjunction with htmx) you should look at diff --git a/www/content/essays/template-fragments.md b/www/content/essays/template-fragments.md index 04de4edc8..327d10086 100644 --- a/www/content/essays/template-fragments.md +++ b/www/content/essays/template-fragments.md @@ -166,6 +166,7 @@ Here are some known implementations of the fragment concept: * [Giraffe.ViewEngine.Htmx](https://github.com/bit-badger/Giraffe.Htmx/tree/main/src/ViewEngine.Htmx) * Rust * [MiniJinja](https://docs.rs/minijinja/latest/minijinja/struct.State.html#method.render_block) + * [Askama](https://askama.readthedocs.io/en/stable/template_syntax.html#block-fragments) * Raku * [Cro Templates](https://github.com/croservices/cro-website/blob/main/docs/reference/cro-webapp-template-syntax.md#fragments) diff --git a/www/content/essays/the-fetchening.md b/www/content/essays/the-fetchening.md new file mode 100644 index 000000000..6262146fb --- /dev/null +++ b/www/content/essays/the-fetchening.md @@ -0,0 +1,269 @@ ++++ +title = "The fetch()ening" +description = """\ + You know, technically, I never said anything about a version *four*""" +date = 2025-11-01 +authors = ["Carson Gross"] +[taxonomies] +tag = ["posts"] ++++ + +![Stop trying to make fetch() happen](/img/fetch.png) + +OK, I said there would never be a version three of htmx. + +But, _technically_, I never said anything about a version *four*... + +## htmx 4: The fetch()ening + +In [The Future of htmx](@/essays/hypermedia-driven-applications.md) I said the following: + +> We are going to work to ensure that htmx is extremely stable in both API & implementation. This means accepting and +documenting the [quirks](https://htmx.org/quirks/) of the current implementation. + +Earlier this year, on a whim, I created [fixi.js](https://github.com/bigskysoftware/fixi), a hyperminimalist implementation +of the ideas in htmx. That work gave me a chance to get a lot more familiar with the `fetch()` and, especially, the +[async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) infrastructure +available in JavaScript. + +In doing that work I began to wonder if that, while the htmx [API](https://htmx.org/reference/#attributes) +is (at least reasonably) correct, maybe there was room for a more dramatic change of the implementation that took +advantage of these features in order to simplify the library. + +Further, changing from ye olde [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) +(a legacy of htmx 1.0 IE support) to [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) would +be a pretty violent change, guaranteed to break at least *some* stuff. + +So I began thinking: if we are going to consider moving to fetch, then maybe we should _also_ use this update as a +chance address at least _some_ of the [quirks & cruft](https://htmx.org/quirks/) that htmx has acquired over its lifetime. + +So, eventually & reluctantly, I have changed my mind: there _will_ be another major version of htmx. + +However, in order to keep my word that there will not be a htmx 3.0, the next release will instead be htmx 4.0. + +## Project Goals + +With htmx 4.0 we are rebuilding the internals of htmx, based on the lessons learned from +fixi.js and [five+ years](https://www.npmjs.com/package/htmx.org/v/0.0.1) of supporting htmx. + +There are three major simplifying changes: + +### The fetch()ening + +The biggest internal change is that `fetch()` will replace `XMLHttpRequest` as the core ajax infrastructure. This +won't actually have a huge effect on most usages of htmx _except_ that the events model will necessarily change due +to the differences between `fetch()` and `XMLHttpRequest`. + +### Explicit Inheritance By Default + +I feel that the biggest mistake in htmx 1.0 & 2.0 was making attribute inheritance implicit. I was inspired by CSS in +doing this, and the results have been roughly the same as CSS: powerful & maddening. + +In htmx 4.0, attribute inheritance will be explicit by default rather than implicit. Explicit inheritance will +be done via the `:inherited` modifier: + +```html +
+ + +
+ Pick a button... +``` + +Here the `hx-target` attribute is explicitly declared as `inherited` on the enclosing `div` and, if it wasn't, the +`button` elements would not inherit the target from it. + +You will be able to revert to htmx 2.0 implicit inheritance behavior via a configuration variable. + +### No Locally Cached History + +Another source of pain for both us and for htmx users is history support. htmx 2.0 stores history in local +cache to make navigation faster. Unfortunately, snapshotting the DOM is often brittle because of third-party +modifications, hidden state, etc. There is a terrible simplicity to the web 1.0 model of blowing everything away and +starting over. There are also security concerns storing history information in session storage. + +In htmx 2.0, we often end up recommending that people facing history-related issues simply disable the cache entirely, +and that usually fixes the problems. + +In htmx 4.0, history support will no longer snapshot the DOM and keep it locally. It will, rather, issue a network +request for the restored content. This is the behavior of 2.0 on a history cache-miss, and it works reliably with +little effort on behalf of htmx users. + +We will offer an extension that enables history caching like in htmx 2.0, but it will be opt-in, rather than the default. + +This tremendously simplifies the htmx codebase and should make the out-of-the-box behavior much more plug-and-play. + +## What Stays The Same? + +Most things. + +The [core](https://dl.acm.org/doi/10.1145/3648188.3675127) functionality of htmx will remain the same, `hx-get`, `hx-post`, +`hx-target`, `hx-boost`, `hx-swap`, `hx-trigger`, etc. + +With a few configuration tweaks, most htmx 2.x based applications should work with htmx 4.x. + +These changes will make the long term maintenance & sustainability of the project much stronger. It will also take +pressure off the 2.0 releases, which can now focus on stability rather than contemplating new features. + +## Upgrading + +htmx 2.0 users _will_ face an upgrade project when moving to 4.0 in a way that they did not have to in moving +from 1.0 to 2.0. + +I am sorry about that, and want to offer two things to address it: + +* htmx 2.0 (like htmx 1.0 & intercooler.js 1.0) will be supported _in perpetuity_, so there is absolutely _no_ pressure to + upgrade your application: if htmx 2.0 is satisfying your hypermedia needs, you can stick with it. +* We will roll htmx 4.0 out slowly, over a multi-year period. As with the htmx 1.0 -> 2.0 upgrade, there will be a long + period where htmx 2.x is `latest` and htmx 4.x is `next` + +## New Features + +Beyond simplifying the implementation of htmx significantly, switching to fetch also gives us the opportunity to add +some nice new features to htmx + +### Streaming Responses & SSE in Core + +By switching to `fetch()`, we can take advantage of its support for +[readable streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams), which +allow for a stream of content to be swapped into the DOM, rather than a single response. + +htmx 1.0 had Server Sent Event support integrated into the library. In htmx 2.0 we pulled this functionality out as an +extension. It turns out that SSE is just a specialized version of a streaming response, so in adding streaming +support, it's an almost-free free two-fer to add that back into core as well. + +This will make incremental response swapping much cleaner and well-supported in htmx. + +### Morphing Swap in Core + +[Three years ago](https://github.com/bigskysoftware/idiomorph/commit/7760e89d9f198b43aa7d39cc4f940f606771f47b) I had +an idea for a DOM morphing algorithm that improved on the initial algorithm pioneered by [morphdom](https://github.com/patrick-steele-idem/morphdom). + +The idea was to use "id sets" to make smarter decisions regarding which nodes to preserve and which nodes to delete when +merging changes into the DOM, and I called this idea "idiomorph". Idiomorph has gone on to be adopted by many other +web project such as [Hotwire](https://hotwired.dev/). + +We strongly considered including it in htmx 2.0, but I decided not too because it worked well as an extension and +htmx 2.0 had already grown larger than I wanted. + +In 4.0, with the complexity savings we achieved by moving to `fetch()`, we can now comfortably fit a `morphInner` and +`morphOuter` swap into core, thanks to the excellent work of Michael West. + +### Explicit <htmx-partial> Tag Support + +htmx has, since very early on, supported a concept of "Out-of-band" swaps: content that is removed from the main HTML +response and swapped into the DOM elsewhere. I have always been a bit ambivalent about them, because they move away +from [Locality of Behavior](https://htmx.org/essays/locality-of-behaviour/), but there is no doubt that they are useful +and often crucial for achieving certain UI patterns. + +Out-of-band swaps started off very simply: if you marked an element as `hx-swap-oob='true'`, htmx would swap the element +as the outer HTML of any existing element already in the DOM with that id. Easy-peasy. + +However, over time, people started asking for different functionality around Out-of-band swaps: prepending, appending, +etc. and the feature began acquiring some fairly baroque syntax to handle all these needs. + +We have come to the conclusion that the problem is that there are really _two_ use cases, both currently trying to be +filled by Out-of-band swaps: + +* A simple, id-based replacement +* A more elaborate swap of partial content + +Therefore, we are introducing the notion of ``s in htmx 4.0 + +A partial element is, under the covers, a template element and, thus, can contain any sort of content you like. It +specifies on itself all the standard htmx options regarding swapping, `hx-target` and `hx-swap` in particular, allowing +you full access to all the standard swapping behavior of htmx without using a specialized syntax. This tremendously +simplifies the mental model for these sorts of needs, and dovetails well with the streaming support we intend to offer. + +Out-of-band swaps will be retained in htmx 4.0, but will go back to their initial, simple focus of simply replacing +an existing element by id. + +### Improved View Transitions Support + +htmx 2.0 has had [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) support since +[April of 2023](https://github.com/bigskysoftware/htmx/blob/master/CHANGELOG.md#190---2023-04-11). In the interceding +two years, support for the feature has grown across browsers (c'mon, safari, you can do it) and we've gained experience +with the feature. + +One thing that has become apparent to us while using them is that, to use them in a stable manner, it is important +to establish a _queue_ of transitions, so each can complete before the other begins. If you don't do this, you can get +visually ugly transition cancellations. + +So, in htmx 4.0 we have added this queue which will ensure that all view transitions complete smoothly. + +CSS transitions will continue to work as before as well, although the swapping model is again made much simpler by the +async runtime. + +We may enable View Transitions by default, the jury is still out on that. + +### Stabilized Event Ordering + +A wonderful thing about `fetch()` and the async support in general is that it is _much_ easier to guarantee a stable +order of events. By linearizing asynchronous code and allowing us to use standard language features like try/catch, +the event model of htmx should be much more predictable and comprehensible. + +We are going to adopt a new standard for event naming to make things even clearer: + +`htmx::[:]` + +So, for example, `htmx:before:request` will be triggered before a request is made. + +### Improved Extension Support + +Another opportunity we have is to take advantage of the `async` behavior of `fetch()` for much better performance in our +preload extension (where we issue a speculative (`GET` only!) request in anticipation of an actual trigger). We have +also added an optimistic update extension to the core extensions, again made easy by the new async features. + +In general, we have opened up the internals of the htmx request/response/swap cycle much more fully to extension developers, +up to and including allowing them to replace the `fetch()` implementation used by htmx for a particular request. There +should not be a need for any hacks to get the behavior you want out of htmx now: the events and the open "context" object +should provide the ability to do almost anything. + +### Improved `hx-on` Support + +In htmx 2.0, I somewhat reluctantly added the [`hx-on`](https://htmx.org/attributes/hx-on/) attributes to support light +scripting inline on elements. I added this because HTML does not allow you to listen for arbitrary events via `on` +attributes: only standard DOM events like `onclick` can be responded to. + +We hemmed and hawed about the syntax and so, unfortunately, there are a few different ways to do it. + +In htmx 4.0 we will adopt a single standard for the `hx-on` attributes: `hx-on:`. Additionally, we are +working to improve the htmx JavaScript API (especially around async operation support) and will make those features +available in `hx-on`: + +```html + +``` + +htmx will never support a fully featured scripting mechanism in core, we recommend something like +[Alpine.js](https://alpinejs.dev/) for that, but our hope is that we can provide a relatively minimalist API that +allows for easy, light async scripting of the DOM. + +I should note that htmx 4.0 will continue to work with `eval()` disabled, but you will need to forego a few features like +`hx-on` if you choose to do so. + +### A Better But Familiar htmx + +All in all, our hope is that htmx 4.0 will feel an awful lot like 2.0, but with better features and, we hope, with fewer bugs. + +## Timeline + +As always, software takes as long as it takes. + +However, our current planned timeline is: + +* An alpha release is available _today_: `htmx@4.0.0-alpha1` +* A 4.0.0 release should be available in early-to-mid 2026 +* 4.0 will be marked `latest` in early-2027ish + +You can track our progress (and see quite a bit of dust flying around) in the `four` branch on +[github](https://github.com/bigskysoftware/htmx/tree/four) and at: + + + +Thank you for your patience and pardon our dust! + +> "Well, when events change, I change my mind. What do you do?" --Paul Samuelson or John Maynard Keynes \ No newline at end of file diff --git a/www/content/extensions/_index.md b/www/content/extensions/_index.md index 9fa82d7ff..16f740bd3 100644 --- a/www/content/extensions/_index.md +++ b/www/content/extensions/_index.md @@ -130,6 +130,10 @@ htmx extensions are split into two categories: {% markdown() %} [dynamic-url](https://github.com/FumingPower3925/htmx-dynamic-url/blob/main/README.md) {% end %} {% markdown() %} Allows dynamic URL path templating using `{varName}` placeholders, resolved via configurable custom function or `window.` fallback. It does not rely on `hx-vals`. Useful when needing to perform requests to paths that depend on application state. {% end %} + + {% markdown() %} [optimistic]([https://github.com/FumingPower3925/htmx-dynamic-url](https://github.com/lorenseanstewart/hx-optimistic/blob/main/README.md) {% end %} + {% markdown() %} This extension provides a way to optimistically update the UI to increase perceived performance {% end %} + Data API diff --git a/www/static/img/fetch.png b/www/static/img/fetch.png new file mode 100644 index 000000000..49eb8087c Binary files /dev/null and b/www/static/img/fetch.png differ diff --git a/www/static/img/rsz_instant_famous.png b/www/static/img/rsz_instant_famous.png new file mode 100644 index 000000000..50a05403f Binary files /dev/null and b/www/static/img/rsz_instant_famous.png differ