Skip to content

Commit 2289e31

Browse files
authored
Add note about the loading mechanism to quirks page (#3387)
1 parent 7ae66f9 commit 2289e31

File tree

1 file changed

+11
-0
lines changed

1 file changed

+11
-0
lines changed

www/content/QUIRKS.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,17 @@ that "If something magically works, then it can also magically break."
176176
Despite this fact, I (Carson) still feel it is useful in many situations, and it is used on the <https://htmx.org>
177177
website.
178178

179+
## Loading htmx asynchronously is unreliable
180+
181+
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).
182+
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.
183+
184+
Our [past attempts](https://github.com/bigskysoftware/htmx/pull/3365#issuecomment-3065080028) to close this gap have all lead to unacceptable regressions.
185+
Therefore, although htmx can be loaded asynchronously, do so at your own risk.
186+
187+
Keep in mind, also, that if your DOM content loads before htmx does, all the htmx-provided functionality will be nonfunctional until htmx loads.
188+
[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.
189+
179190
## The JavaScript API Is Not A Focus
180191

181192
htmx is a hypermedia-oriented front end library. This means that htmx enhances HTML via

0 commit comments

Comments
 (0)