From 90a91a60e0fcd2d7c42e04c615177cba89c33151 Mon Sep 17 00:00:00 2001 From: Mariss Tubelis Date: Fri, 14 Feb 2025 22:37:21 +0100 Subject: [PATCH] Extension docs: npm, bundler, min/unmin and SRI hash instructions (#3127) * Extensions docs: add npm/bundler installation guide and up versions numbers for links * Revert extensions._index.md table change * Update docs.md extension installation and integration instruction * Move extension installation and enabling to new sections in docs.md * Update extension installation guidelines * Update idiomorph installation guidelines * Minor consistency edits * Make the need for hx-ext clearer * Fix typos and note for community repos not hosted outside this repo --- www/content/docs.md | 71 ++++++++++++++++------ www/content/extensions/head-support.md | 29 ++++++++- www/content/extensions/htmx-1-compat.md | 28 ++++++++- www/content/extensions/idiomorph.md | 28 ++++++++- www/content/extensions/preload.md | 30 +++++++-- www/content/extensions/response-targets.md | 29 ++++++++- www/content/extensions/sse.md | 27 +++++++- www/content/extensions/ws.md | 27 +++++++- 8 files changed, 227 insertions(+), 42 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index e94eb0b5..d28c3173 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -1120,30 +1120,11 @@ htmx provides an [extensions](/extensions) mechanism that allows you to customiz Extensions [are defined in javascript](/extensions/building) and then enabled via the [`hx-ext`](@/attributes/hx-ext.md) attribute. -Here is how you would install the [idiomorph](/extensions/idiomorph) extension, which allows you to use the -[Idiomorph](https://github.com/bigskysoftware/idiomorph) DOM morphing algorithms for htmx swaps: - -```html - - - - - ... - - ... - -``` - -First the extension is included (it should be included *after* `htmx.js` is included), then the extension is referenced -by name via the `hx-ext` attribute. This enables you to then use the `morph` swap. - ### Core Extensions htmx supports a few "core" extensions, which are supported by the htmx development team: -* [head-support](/extensions/head-support) - support for merging head tag information (styles, etc.) in htmx requests | +* [head-support](/extensions/head-support) - support for merging head tag information (styles, etc.) in htmx requests * [htmx-1-compat](/extensions/htmx-1-compat) - restores htmx 1 defaults & functionality * [idiomorph](/extensions/idiomorph) - supports the `morph` swap strategy using idiomorph * [preload](/extensions/preload) - allows you to preload content for better performance @@ -1153,6 +1134,56 @@ htmx supports a few "core" extensions, which are supported by the htmx developme You can see all available extensions on the [Extensions](/extensions) page. +### Installing Extensions + +The fastest way to install htmx extensions created by others is to load them via a CDN. Remember to always include the core htmx library before the extensions and [enable the extension](#enabling-extensions). For example, if you would like to use the [response-targets](/extensions/response-targets) extension, you can add this to your head tag: +```HTML + + + + + + ... +``` +An unminified version is also available at `https://unpkg.com/htmx-ext-extension-name/dist/extension-name.js` (replace `extension-name` with the name of the extension). + +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install htmx extensions is to simply copy them into your project. Download the extension from `https://unpkg.com/htmx-ext-extension-name` (replace `extension-name` with the name of the extension) e.g., https://unpkg.com/htmx-ext-response-targets. Then add it to the appropriate directory in your project and include it where necessary with a ` +The fastest way to install `head-support` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). +```HTML + + + + + +... +``` +An unminified version is also available at https://unpkg.com/htmx-ext-head-support/dist/head-support.js. + +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `head-support` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-head-support`, add it to the appropriate directory in your project and include it where necessary with a ` + + + +... +``` +An unminified version is also available at https://unpkg.com/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js. - +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `htmx-1-compat` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-htmx-1-compat`, add it to the appropriate directory in your project and include it where necessary with a ` +The fastest way to install `idiomorph` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). +```HTML + + + + + +``` +An unminified version is also available at https://unpkg.com/idiomorph/dist/idiomorph.js. + +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `idiomorph` is to simply copy it into your project. Download the extension from `https://unpkg.com/idiomorph`, add it to the appropriate directory in your project and include it where necessary with a ` +The fastest way to install `preload` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). +```HTML + + + + + +... +``` +An unminified version is also available at https://unpkg.com/htmx-ext-preload/dist/preload.js. + +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `preload` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-preload`, add it to the appropriate directory in your project and include it where necessary with a ` +The fastest way to install `response-targets` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). +```HTML + + + + + +... +``` +An unminified version is also available at https://unpkg.com/htmx-ext-response-targets/dist/response-targets.js. + +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `response-targets` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-response-targets`, add it to the appropriate directory in your project and include it where necessary with a ` + + + +``` +An unminified version is also available at https://unpkg.com/htmx-ext-sse/dist/sse.js. - +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `sse` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-sse`, add it to the appropriate directory in your project and include it where necessary with a ` + + + +``` +An unminified version is also available at https://unpkg.com/htmx-ext-ws/dist/ws.js. - +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `ws` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-ws`, add it to the appropriate directory in your project and include it where necessary with a `