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
author: Mariss Tubelis <mariss@mariss.no> 2025-02-14 22:37:21 +0100
committer: GitHub <noreply@github.com> 2025-02-14 22:37:21 +0100
commit: 90a91a60e0fcd2d7c42e04c615177cba89c33151 (patch)
tree: 294b8e9db60d721d5ac57017b00fa5877d631bdb
parent: 0f9c4202ba5c0dd7bd6e6fb430b176b0c9bdba18 (diff)
download: htmx-90a91a60e0fcd2d7c42e04c615177cba89c33151.tar.gz
htmx-90a91a60e0fcd2d7c42e04c615177cba89c33151.zip
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
-<head>
-  <script src="https://unpkg.com/idiomorph@0.3.0/dist/idiomorph-ext.min.js"></script>
-</head>
-<body hx-ext="morph">
-  ...
-  <button hx-post="/example" hx-swap="morph" hx-target="#content">
-    Update Content
-  </button>
-  ...
-</body>
-```
-
-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
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="extension-name">
+    ...
+```
+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 `<script>` tag.
+
+For npm-style build systems, you can install htmx extensions via [npm](https://www.npmjs.com/) (replace `extension-name` with the name of the extension):
+```shell
+npm install htmx-ext-extension-name
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-extension-name/dist/extension-name.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `htmx-ext-extension-name` via npm (replace `extension-name` with the name of the extension)
+- 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 
+```
+
+Note: [Idiomorph](/extensions/idiomorph) does not follow the naming convention of htmx extensions. Use `idiomorph` instead of `htmx-ext-idiomorph`. For example, `https://unpkg.com/idiomorph` or `npm install idiomorph`.
+
+Note: Community extensions hosted outside this repository might have different installation instructions. Please check the corresponding repository for set-up guidance.
+
+### Enabling Extensions
+
+To enable an extension, add a `hx-ext="extension-name"` attribute to `<body>` or another HTML element (replace `extension-name` with the name of the extension). The extension will be applied to all child elements.
+
+The following example shows how to enable [response-targets](/extensions/response-targets) extension, allowing you to specify different target elements to be swapped based on HTTP response code.
+```html
+<body hx-ext="response-targets">
+    ...
+    <button hx-post="/register" hx-target="#response-div" hx-target-404="#not-found">
+        Register!
+    </button>
+    <div id="response-div"></div>
+    <div id="not-found"></div>
+    ...
+</body>
+```
+
 ### Creating Extensions
 
 If you are interested in adding your own extension to htmx, please [see the extension docs](/extensions/building).
diff --git a/www/content/extensions/head-support.md b/www/content/extensions/head-support.md
index dd034de7..67c1aaef 100644
--- a/www/content/extensions/head-support.md
+++ b/www/content/extensions/head-support.md
@@ -13,10 +13,33 @@ The [`hx-boost`](@/attributes/hx-boost.md) attribute moved htmx closer to this w
 support for extracting the `title` tag out of head elements was eventually added, but full head tag support has never been
 a feature of the library.  This extension addresses that shortcoming.
 
-## Install
+## Installing
 
-```html
-<script src="https://unpkg.com/htmx-ext-head-support@2.0.1/head-support.js"></script>
+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
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/htmx-ext-head-support@2.0.2" integrity="sha384-cvMqHzjCJsOHgGuyB3sWXaUSv/Krm0BdzjuI1rtkjCbL1l1oHJx+cHyVRJhyuEz0" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="head-support">
+...
+```
+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 `<script>` tag.
+
+For npm-style build systems, you can install `head-support` via [npm](https://www.npmjs.com/):
+```shell
+npm install htmx-ext-head-support
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-head-support/dist/head-support.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `htmx-ext-head-support` via npm
+- Import both packages to your `index.js`
+```JS
+import `htmx.org`;
+import `htmx-ext-head-support`; 
 ```
 
 ## Usage
diff --git a/www/content/extensions/htmx-1-compat.md b/www/content/extensions/htmx-1-compat.md
index 967377f7..2e157c02 100644
--- a/www/content/extensions/htmx-1-compat.md
+++ b/www/content/extensions/htmx-1-compat.md
@@ -4,11 +4,33 @@ title = "htmx 1.x Compatibility Extension"
 
 The `htmx-1-compat` extension allows you to almost seamlessly upgrade from htmx 1.x to htmx 2.
 
-## Install
+## Installing
+
+The fastest way to install `htmx-1-compat` is to load it via a CDN. Remember to always include the core htmx library before the extension and enable the extension.
+```HTML
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/htmx-ext-htmx-1-compat@2.0.0" integrity="sha384-lcvVWaNjF5zPPUeeWmC0OkJ2MLqoWLlkAabuGm+EuMSTfGo5WRyHrNaAp0cJr9Pg" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="htmx-1-compat">
+...
+```
+An unminified version is also available at https://unpkg.com/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js.
 
-```html
+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 `<script>` tag.
 
-<script src="https://unpkg.com/htmx-ext-htmx-1-compat@2.0.0/htmx-1-compat.js"></script>
+For npm-style build systems, you can install `htmx-1-compat` via [npm](https://www.npmjs.com/):
+```shell
+npm install htmx-ext-htmx-1-compat
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `htmx-ext-htmx-1-compat` via npm
+- Import both packages to your `index.js`
+```JS
+import `htmx.org`;
+import `htmx-ext-htmx-1-compat`; 
 ```
 
 ## What it covers
diff --git a/www/content/extensions/idiomorph.md b/www/content/extensions/idiomorph.md
index ef7c84f1..bd75dad7 100644
--- a/www/content/extensions/idiomorph.md
+++ b/www/content/extensions/idiomorph.md
@@ -10,10 +10,32 @@ much smoother transition between the two states.
 You can use the idiomorph morphing algorithm as a [swapping](@attributes/hx-swap) strategy by including the idiomorph 
 extension.
 
-## Install
+## Installing
 
-```html
-<script src="https://unpkg.com/idiomorph@0.3.0/dist/idiomorph-ext.min.js"></script>
+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
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/idiomorph@0.3.0" integrity="sha384-tg/2Ca9U/RohyxmGCb8qJVR3j9cswtKbdRSXOaPX/aDDOW1bfbeyV+7G9ifYF4bC" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="morph">
+```
+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 `<script>` tag.
+
+For npm-style build systems, you can install `idiomorph` via [npm](https://www.npmjs.com/):
+```shell
+npm install idiomorph
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/idiomorph/dist/idiomorph.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `idiomorph` via npm
+- Import both packages to your `index.js`
+```JS
+import `htmx.org`;
+import `idiomorph`; 
 ```
 
 ## Usage
diff --git a/www/content/extensions/preload.md b/www/content/extensions/preload.md
index fd0fda9f..9afa70e1 100644
--- a/www/content/extensions/preload.md
+++ b/www/content/extensions/preload.md
@@ -10,10 +10,33 @@ behavior to fit your applications needs and use cases.
 too many resources can negatively impact your visitors' bandwidth and your server performance by initiating too many
 unused requests. Use this extension carefully!
 
-## Install
+## Installing
+
+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
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/htmx-ext-preload@2.1.0" integrity="sha384-fkzubQiTB69M7XTToqW6tplvxAOJkqPl5JmLAbumV2EacmuJb8xEP9KnJafk/rg8" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="preload">
+...
+```
+An unminified version is also available at https://unpkg.com/htmx-ext-preload/dist/preload.js.
 
-```html
-<script src="https://unpkg.com/htmx-ext-preload@2.1.0/preload.js"></script>
+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 `<script>` tag.
+
+For npm-style build systems, you can install `preload` via [npm](https://www.npmjs.com/):
+```shell
+npm install htmx-ext-preload
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-preload/dist/preload.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `htmx-ext-preload` via npm
+- Import both packages to your `index.js`
+```JS
+import `htmx.org`;
+import `htmx-ext-preload`; 
 ```
 
 ## Usage
@@ -23,7 +46,6 @@ and `hx-get` elements you want to preload. By default, resources will be loaded
 giving your application a roughly 100-200ms head start on serving responses. See configuration below for other options.
 
 ```html
-
 <body hx-ext="preload">
 <h1>What Works</h2>
     <a href="/server/1" preload>WILL BE requested using a standard XMLHttpRequest() and default options (below)</a>
diff --git a/www/content/extensions/response-targets.md b/www/content/extensions/response-targets.md
index c0306d50..8b2ac954 100644
--- a/www/content/extensions/response-targets.md
+++ b/www/content/extensions/response-targets.md
@@ -22,10 +22,33 @@ The value of each attribute can be:
 * `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
 (e.g `previous .error` will target the closest previous sibling with `error` class)
 
-## Install
+## Installing
+
+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
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="response-targets">
+...
+```
+An unminified version is also available at https://unpkg.com/htmx-ext-response-targets/dist/response-targets.js.
 
-```html
-<script src="https://unpkg.com/htmx-ext-response-targets@2.0.0/response-targets.js"></script>
+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 `<script>` tag.
+
+For npm-style build systems, you can install `response-targets` via [npm](https://www.npmjs.com/):
+```shell
+npm install htmx-ext-response-targets
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-response-targets/dist/response-targets.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `htmx-ext-response-targets` via npm
+- Import both packages to your `index.js`
+```JS
+import `htmx.org`;
+import `htmx-ext-response-targets`; 
 ```
 
 ## Configure (optional)
diff --git a/www/content/extensions/sse.md b/www/content/extensions/sse.md
index c5939bcf..bf1ae2e9 100644
--- a/www/content/extensions/sse.md
+++ b/www/content/extensions/sse.md
@@ -24,11 +24,32 @@ Use the following attributes to configure how SSE connections behave:
 * `sse-close=<message-name>` - To close the EventStream gracefully when that message is received. This might be helpful
   if you want to send information to a client that will eventually stop.
 
-## Install
+## Installing
+
+The fastest way to install `sse` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
+```HTML
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/htmx-ext-sse@2.2.2" integrity="sha384-Y4gc0CK6Kg+hmulDc6rZPJu0tqvk7EWlih0Oh+2OkAi1ZDlCbBDCQEE2uVk472Ky" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="sse">
+```
+An unminified version is also available at https://unpkg.com/htmx-ext-sse/dist/sse.js.
 
-```html
+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 `<script>` tag.
 
-<script src="https://unpkg.com/htmx-ext-sse@2.2.2/sse.js"></script>
+For npm-style build systems, you can install `sse` via [npm](https://www.npmjs.com/):
+```shell
+npm install htmx-ext-sse
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-sse/dist/sse.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `htmx-ext-sse` via npm
+- Import both packages to your `index.js`
+```JS
+import `htmx.org`;
+import `htmx-ext-sse`; 
 ```
 
 ## Usage
diff --git a/www/content/extensions/ws.md b/www/content/extensions/ws.md
index d35ea7e8..3e247783 100644
--- a/www/content/extensions/ws.md
+++ b/www/content/extensions/ws.md
@@ -18,11 +18,32 @@ Use the following attributes to configure how WebSockets behave:
   event
   or the event specified by [`hx-trigger`])
 
-## Install
+## Installing
+
+The fastest way to install `ws` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
+```HTML
+<head>
+    <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
+    <script src="https://unpkg.com/htmx-ext-ws@2.0.2" integrity="sha384-vuKxTKv5TX/b3lLzDKP2U363sOAoRo5wSvzzc3LJsbaQRSBSS+3rKKHcOx5J8doU" crossorigin="anonymous"></script>
+</head>
+<body hx-ext="ws">
+```
+An unminified version is also available at https://unpkg.com/htmx-ext-ws/dist/ws.js.
 
-```html
+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 `<script>` tag.
 
-<script src="https://unpkg.com/htmx-ext-ws@2.0.1/ws.js"></script>
+For npm-style build systems, you can install `ws` via [npm](https://www.npmjs.com/):
+```shell
+npm install htmx-ext-ws
+```
+After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-ws/dist/ws.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.
+
+If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
+- Install `htmx.org` and `htmx-ext-ws` via npm
+- Import both packages to your `index.js`
+```JS
+import `htmx.org`;
+import `htmx-ext-ws`; 
 ```
 
 ## Usage
author	Mariss Tubelis <mariss@mariss.no>	2025-02-14 22:37:21 +0100
committer	GitHub <noreply@github.com>	2025-02-14 22:37:21 +0100
commit	90a91a60e0fcd2d7c42e04c615177cba89c33151 (patch)
tree	294b8e9db60d721d5ac57017b00fa5877d631bdb
parent	0f9c4202ba5c0dd7bd6e6fb430b176b0c9bdba18 (diff)
download	htmx-90a91a60e0fcd2d7c42e04c615177cba89c33151.tar.gz htmx-90a91a60e0fcd2d7c42e04c615177cba89c33151.zip