Skip to content

Commit 90a91a6

Browse files
marisstmarisst
authored
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
1 parent 0f9c420 commit 90a91a6

File tree

8 files changed

+227
-42
lines changed

8 files changed

+227
-42
lines changed

‎www/content/docs.md‎

Lines changed: 51 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1120,30 +1120,11 @@ htmx provides an [extensions](/extensions) mechanism that allows you to customiz
11201120
Extensions [are defined in javascript](/extensions/building) and then enabled via
11211121
the [`hx-ext`](@/attributes/hx-ext.md) attribute.
11221122

1123-
Here is how you would install the [idiomorph](/extensions/idiomorph) extension, which allows you to use the
1124-
[Idiomorph](https://github.com/bigskysoftware/idiomorph) DOM morphing algorithms for htmx swaps:
1125-
1126-
```html
1127-
<head>
1128-
<script src="https://unpkg.com/idiomorph@0.3.0/dist/idiomorph-ext.min.js"></script>
1129-
</head>
1130-
<body hx-ext="morph">
1131-
...
1132-
<button hx-post="/example" hx-swap="morph" hx-target="#content">
1133-
Update Content
1134-
</button>
1135-
...
1136-
</body>
1137-
```
1138-
1139-
First the extension is included (it should be included *after* `htmx.js` is included), then the extension is referenced
1140-
by name via the `hx-ext` attribute. This enables you to then use the `morph` swap.
1141-
11421123
### Core Extensions
11431124

11441125
htmx supports a few "core" extensions, which are supported by the htmx development team:
11451126

1146-
* [head-support](/extensions/head-support) - support for merging head tag information (styles, etc.) in htmx requests |
1127+
* [head-support](/extensions/head-support) - support for merging head tag information (styles, etc.) in htmx requests
11471128
* [htmx-1-compat](/extensions/htmx-1-compat) - restores htmx 1 defaults & functionality
11481129
* [idiomorph](/extensions/idiomorph) - supports the `morph` swap strategy using idiomorph
11491130
* [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
11531134

11541135
You can see all available extensions on the [Extensions](/extensions) page.
11551136

1137+
### Installing Extensions
1138+
1139+
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:
1140+
```HTML
1141+
<head>
1142+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
1143+
<script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
1144+
</head>
1145+
<body hx-ext="extension-name">
1146+
...
1147+
```
1148+
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).
1149+
1150+
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.
1151+
1152+
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):
1153+
```shell
1154+
npm install htmx-ext-extension-name
1155+
```
1156+
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.
1157+
1158+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
1159+
- Install `htmx.org` and `htmx-ext-extension-name` via npm (replace `extension-name` with the name of the extension)
1160+
- Import both packages to your `index.js`
1161+
```JS
1162+
import `htmx.org`;
1163+
import `htmx-ext-extension-name`; // replace `extension-name` with the name of the extension
1164+
```
1165+
1166+
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`.
1167+
1168+
Note: Community extensions hosted outside this repository might have different installation instructions. Please check the corresponding repository for set-up guidance.
1169+
1170+
### Enabling Extensions
1171+
1172+
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.
1173+
1174+
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.
1175+
```html
1176+
<body hx-ext="response-targets">
1177+
...
1178+
<button hx-post="/register" hx-target="#response-div" hx-target-404="#not-found">
1179+
Register!
1180+
</button>
1181+
<div id="response-div"></div>
1182+
<div id="not-found"></div>
1183+
...
1184+
</body>
1185+
```
1186+
11561187
### Creating Extensions
11571188

11581189
If you are interested in adding your own extension to htmx, please [see the extension docs](/extensions/building).

‎www/content/extensions/head-support.md‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,33 @@ The [`hx-boost`](@/attributes/hx-boost.md) attribute moved htmx closer to this w
1313
support for extracting the `title` tag out of head elements was eventually added, but full head tag support has never been
1414
a feature of the library. This extension addresses that shortcoming.
1515

16-
## Install
16+
## Installing
1717

18-
```html
19-
<script src="https://unpkg.com/htmx-ext-head-support@2.0.1/head-support.js"></script>
18+
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).
19+
```HTML
20+
<head>
21+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
22+
<script src="https://unpkg.com/htmx-ext-head-support@2.0.2" integrity="sha384-cvMqHzjCJsOHgGuyB3sWXaUSv/Krm0BdzjuI1rtkjCbL1l1oHJx+cHyVRJhyuEz0" crossorigin="anonymous"></script>
23+
</head>
24+
<body hx-ext="head-support">
25+
...
26+
```
27+
An unminified version is also available at https://unpkg.com/htmx-ext-head-support/dist/head-support.js.
28+
29+
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.
30+
31+
For npm-style build systems, you can install `head-support` via [npm](https://www.npmjs.com/):
32+
```shell
33+
npm install htmx-ext-head-support
34+
```
35+
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.
36+
37+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
38+
- Install `htmx.org` and `htmx-ext-head-support` via npm
39+
- Import both packages to your `index.js`
40+
```JS
41+
import `htmx.org`;
42+
import `htmx-ext-head-support`;
2043
```
2144

2245
## Usage

‎www/content/extensions/htmx-1-compat.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,33 @@ title = "htmx 1.x Compatibility Extension"
44

55
The `htmx-1-compat` extension allows you to almost seamlessly upgrade from htmx 1.x to htmx 2.
66

7-
## Install
7+
## Installing
8+
9+
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.
10+
```HTML
11+
<head>
12+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
13+
<script src="https://unpkg.com/htmx-ext-htmx-1-compat@2.0.0" integrity="sha384-lcvVWaNjF5zPPUeeWmC0OkJ2MLqoWLlkAabuGm+EuMSTfGo5WRyHrNaAp0cJr9Pg" crossorigin="anonymous"></script>
14+
</head>
15+
<body hx-ext="htmx-1-compat">
16+
...
17+
```
18+
An unminified version is also available at https://unpkg.com/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js.
819

9-
```html
20+
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.
1021

11-
<script src="https://unpkg.com/htmx-ext-htmx-1-compat@2.0.0/htmx-1-compat.js"></script>
22+
For npm-style build systems, you can install `htmx-1-compat` via [npm](https://www.npmjs.com/):
23+
```shell
24+
npm install htmx-ext-htmx-1-compat
25+
```
26+
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.
27+
28+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
29+
- Install `htmx.org` and `htmx-ext-htmx-1-compat` via npm
30+
- Import both packages to your `index.js`
31+
```JS
32+
import `htmx.org`;
33+
import `htmx-ext-htmx-1-compat`;
1234
```
1335

1436
## What it covers

‎www/content/extensions/idiomorph.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,32 @@ much smoother transition between the two states.
1010
You can use the idiomorph morphing algorithm as a [swapping](@attributes/hx-swap) strategy by including the idiomorph
1111
extension.
1212

13-
## Install
13+
## Installing
1414

15-
```html
16-
<script src="https://unpkg.com/idiomorph@0.3.0/dist/idiomorph-ext.min.js"></script>
15+
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).
16+
```HTML
17+
<head>
18+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
19+
<script src="https://unpkg.com/idiomorph@0.3.0" integrity="sha384-tg/2Ca9U/RohyxmGCb8qJVR3j9cswtKbdRSXOaPX/aDDOW1bfbeyV+7G9ifYF4bC" crossorigin="anonymous"></script>
20+
</head>
21+
<body hx-ext="morph">
22+
```
23+
An unminified version is also available at https://unpkg.com/idiomorph/dist/idiomorph.js.
24+
25+
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.
26+
27+
For npm-style build systems, you can install `idiomorph` via [npm](https://www.npmjs.com/):
28+
```shell
29+
npm install idiomorph
30+
```
31+
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.
32+
33+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
34+
- Install `htmx.org` and `idiomorph` via npm
35+
- Import both packages to your `index.js`
36+
```JS
37+
import `htmx.org`;
38+
import `idiomorph`;
1739
```
1840

1941
## Usage

‎www/content/extensions/preload.md‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,33 @@ behavior to fit your applications needs and use cases.
1010
too many resources can negatively impact your visitors' bandwidth and your server performance by initiating too many
1111
unused requests. Use this extension carefully!
1212

13-
## Install
13+
## Installing
14+
15+
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).
16+
```HTML
17+
<head>
18+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
19+
<script src="https://unpkg.com/htmx-ext-preload@2.1.0" integrity="sha384-fkzubQiTB69M7XTToqW6tplvxAOJkqPl5JmLAbumV2EacmuJb8xEP9KnJafk/rg8" crossorigin="anonymous"></script>
20+
</head>
21+
<body hx-ext="preload">
22+
...
23+
```
24+
An unminified version is also available at https://unpkg.com/htmx-ext-preload/dist/preload.js.
1425

15-
```html
16-
<script src="https://unpkg.com/htmx-ext-preload@2.1.0/preload.js"></script>
26+
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.
27+
28+
For npm-style build systems, you can install `preload` via [npm](https://www.npmjs.com/):
29+
```shell
30+
npm install htmx-ext-preload
31+
```
32+
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.
33+
34+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
35+
- Install `htmx.org` and `htmx-ext-preload` via npm
36+
- Import both packages to your `index.js`
37+
```JS
38+
import `htmx.org`;
39+
import `htmx-ext-preload`;
1740
```
1841

1942
## Usage
@@ -23,7 +46,6 @@ and `hx-get` elements you want to preload. By default, resources will be loaded
2346
giving your application a roughly 100-200ms head start on serving responses. See configuration below for other options.
2447

2548
```html
26-
2749
<body hx-ext="preload">
2850
<h1>What Works</h2>
2951
<a href="/server/1" preload>WILL BE requested using a standard XMLHttpRequest() and default options (below)</a>

‎www/content/extensions/response-targets.md‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,33 @@ The value of each attribute can be:
2222
* `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
2323
(e.g `previous .error` will target the closest previous sibling with `error` class)
2424

25-
## Install
25+
## Installing
26+
27+
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).
28+
```HTML
29+
<head>
30+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
31+
<script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
32+
</head>
33+
<body hx-ext="response-targets">
34+
...
35+
```
36+
An unminified version is also available at https://unpkg.com/htmx-ext-response-targets/dist/response-targets.js.
2637

27-
```html
28-
<script src="https://unpkg.com/htmx-ext-response-targets@2.0.0/response-targets.js"></script>
38+
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.
39+
40+
For npm-style build systems, you can install `response-targets` via [npm](https://www.npmjs.com/):
41+
```shell
42+
npm install htmx-ext-response-targets
43+
```
44+
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.
45+
46+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
47+
- Install `htmx.org` and `htmx-ext-response-targets` via npm
48+
- Import both packages to your `index.js`
49+
```JS
50+
import `htmx.org`;
51+
import `htmx-ext-response-targets`;
2952
```
3053

3154
## Configure (optional)

‎www/content/extensions/sse.md‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,32 @@ Use the following attributes to configure how SSE connections behave:
2424
* `sse-close=<message-name>` - To close the EventStream gracefully when that message is received. This might be helpful
2525
if you want to send information to a client that will eventually stop.
2626

27-
## Install
27+
## Installing
28+
29+
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).
30+
```HTML
31+
<head>
32+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
33+
<script src="https://unpkg.com/htmx-ext-sse@2.2.2" integrity="sha384-Y4gc0CK6Kg+hmulDc6rZPJu0tqvk7EWlih0Oh+2OkAi1ZDlCbBDCQEE2uVk472Ky" crossorigin="anonymous"></script>
34+
</head>
35+
<body hx-ext="sse">
36+
```
37+
An unminified version is also available at https://unpkg.com/htmx-ext-sse/dist/sse.js.
2838

29-
```html
39+
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.
3040

31-
<script src="https://unpkg.com/htmx-ext-sse@2.2.2/sse.js"></script>
41+
For npm-style build systems, you can install `sse` via [npm](https://www.npmjs.com/):
42+
```shell
43+
npm install htmx-ext-sse
44+
```
45+
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.
46+
47+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
48+
- Install `htmx.org` and `htmx-ext-sse` via npm
49+
- Import both packages to your `index.js`
50+
```JS
51+
import `htmx.org`;
52+
import `htmx-ext-sse`;
3253
```
3354

3455
## Usage

‎www/content/extensions/ws.md‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,32 @@ Use the following attributes to configure how WebSockets behave:
1818
event
1919
or the event specified by [`hx-trigger`])
2020

21-
## Install
21+
## Installing
22+
23+
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).
24+
```HTML
25+
<head>
26+
<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
27+
<script src="https://unpkg.com/htmx-ext-ws@2.0.2" integrity="sha384-vuKxTKv5TX/b3lLzDKP2U363sOAoRo5wSvzzc3LJsbaQRSBSS+3rKKHcOx5J8doU" crossorigin="anonymous"></script>
28+
</head>
29+
<body hx-ext="ws">
30+
```
31+
An unminified version is also available at https://unpkg.com/htmx-ext-ws/dist/ws.js.
2232

23-
```html
33+
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.
2434

25-
<script src="https://unpkg.com/htmx-ext-ws@2.0.1/ws.js"></script>
35+
For npm-style build systems, you can install `ws` via [npm](https://www.npmjs.com/):
36+
```shell
37+
npm install htmx-ext-ws
38+
```
39+
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.
40+
41+
If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
42+
- Install `htmx.org` and `htmx-ext-ws` via npm
43+
- Import both packages to your `index.js`
44+
```JS
45+
import `htmx.org`;
46+
import `htmx-ext-ws`;
2647
```
2748

2849
## Usage

0 commit comments

Comments
 (0)