itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-09-27 04:50:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add note about the loading mechanism to quirks page (#3387)

Browse Source
This commit is contained in:
Alexander Petros 2025-07-21 22:42:49 -04:00 committed by GitHub
parent 7ae66f9b33
commit 2289e3176e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 11 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
www/content/QUIRKS.md
View File

@ -176,6 +176,17 @@ that "If something magically works, then it can also magically break."
Despite this fact, I (Carson) still feel it is useful in many situations, and it is used on the <https://htmx.org>
website.
## Loading htmx asynchronously is unreliable
htmx is designed to be loaded with a standard, blocking `<script>` tag, not one that is a [module](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#module) or [deferred](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#defer).
Although we make a [best-effort attempt](https://github.com/bigskysoftware/htmx/blob/7ae66f9b33a5d39ad4084b0697ea34a6bf559cda/src/htmx.js#L5039-L5058) to initialize htmx regardless of when in the document lifecycle the script is loaded, there are some use-cases that slip through the cracks, typically ones that involve bundling or AJAX insertion of htmx itself.
Our [past attempts](https://github.com/bigskysoftware/htmx/pull/3365#issuecomment-3065080028) to close this gap have all lead to unacceptable regressions.
Therefore, although htmx can be loaded asynchronously, do so at your own risk.
Keep in mind, also, that if your DOM content loads before htmx does, all the htmx-provided functionality will be nonfunctional until htmx loads.
[Prefetching](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch) (or even "regular" fetching) htmx before you need it is one possible way to resolve this problem.
## The JavaScript API Is Not A Focus
htmx is a hypermedia-oriented front end library. This means that htmx enhances HTML via