From f16922a6fb29730304f97bae3197db78af8aa6a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Wi=C5=9Bniowski?= Date: Mon, 24 Jun 2024 09:56:52 +0200 Subject: [PATCH 1/6] Update npm, webpack and vite installation guidelines --- www/content/docs.md | 55 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 4 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index 171c31f06..a6b06d2d0 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -152,14 +152,14 @@ For npm-style build systems, you can install htmx via [npm](https://www.npmjs.co npm install htmx.org@2.0.1 ``` -After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx.js` (or `.min.js`). +After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx[esm, cjs, amd].js` (or `.min.js`). For example, you might bundle htmx with some extensions and project-specific code. ### Webpack -If you are using webpack to manage your javascript: +If you are using [webpack](https://webpack.js.org) to manage your javascript: -* Install `htmx` via your favourite package manager (like npm or yarn) +* Install `htmx.org` via your favourite package manager (like npm or yarn) * Add the import to your `index.js` ```js @@ -178,7 +178,54 @@ import 'path/to/my_custom.js'; * Then add this code to the file: ```js -window.htmx = require('htmx.org'); +import htmx from "htmx.org/dist/htmx.esm"; +window.htmx = htmx; +``` + +* Finally, rebuild your bundle + +### Vite + +If you are using [Vite](https://vitejs.dev) to manage your javascript: + +* Install `htmx.org` via your favourite package manager (like npm or yarn) +* Add the import to your entrypoint(s). For example if you +[serve the HTML using a backend](https://vitejs.dev/guide/backend-integration.html) +and your vite.config.js looks like this: + +```js +export default defineConfig({ + build: { + manifest: true, + rollupOptions: { + input: '/path/to/main.js', + }, + }, +}) +``` + +* then add the following import to the `/path/to/main.js` + +```js +import 'htmx.org'; +``` + +You will probably also want to use the global htmx variable so that you can access methods like +`htmx.onLoad` or use npm-installed plugins that expect `htmx` global to be present. +To do this you need to inject it to the window scope: + +* Add the following to your `vite.config.js`: + +```js +export default defineConfig({ + build: { + plugins: [ + inject({ + htmx: 'htmx.org/dist/htmx.esm', + }), + ], + }, +}) ``` * Finally, rebuild your bundle From bc1bf08701a987519babfbc94f35c7e25959ba93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Wi=C5=9Bniowski?= Date: Mon, 24 Jun 2024 10:34:06 +0200 Subject: [PATCH 2/6] Reorganize Vite installation instructions --- www/content/docs.md | 65 +++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 38 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index a6b06d2d0..2604d8ee3 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -188,47 +188,36 @@ window.htmx = htmx; If you are using [Vite](https://vitejs.dev) to manage your javascript: -* Install `htmx.org` via your favourite package manager (like npm or yarn) -* Add the import to your entrypoint(s). For example if you -[serve the HTML using a backend](https://vitejs.dev/guide/backend-integration.html) -and your vite.config.js looks like this: - -```js -export default defineConfig({ - build: { - manifest: true, - rollupOptions: { - input: '/path/to/main.js', - }, - }, -}) -``` - -* then add the following import to the `/path/to/main.js` +1. Install `htmx.org` via your favourite package manager (like npm or yarn) -```js -import 'htmx.org'; -``` +2. Load htmx -You will probably also want to use the global htmx variable so that you can access methods like + You will probably want to use the global htmx variable so that you can access methods like `htmx.onLoad` or use npm-installed plugins that expect `htmx` global to be present. -To do this you need to inject it to the window scope: - -* Add the following to your `vite.config.js`: - -```js -export default defineConfig({ - build: { - plugins: [ - inject({ - htmx: 'htmx.org/dist/htmx.esm', - }), - ], - }, -}) -``` - -* Finally, rebuild your bundle + + To achieve this you need to inject `htmx` into the window scope. + + * Add the following to your `vite.config.js`: + + ```js + export default defineConfig({ + build: { + plugins: [ + inject({ + htmx: 'htmx.org/dist/htmx.esm', + }), + ], + }, + }) + ``` + + Alternatively, if you don't need the `htmx` global variable then add the following to + your entry point [main.js file](https://vitejs.dev/guide/backend-integration.html): + ```js + import 'htmx.org'; + ``` + +3. Finally, rebuild your bundle ## AJAX From 1c7d0646b651787415d0e64f4fe88de9562dea4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Wi=C5=9Bniowski?= Date: Tue, 25 Jun 2024 08:46:47 +0200 Subject: [PATCH 3/6] Rewrite instructions to include suggestions from the code review --- www/content/docs.md | 95 +++++++++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 43 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index 2604d8ee3..328337ebd 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -152,72 +152,81 @@ For npm-style build systems, you can install htmx via [npm](https://www.npmjs.co npm install htmx.org@2.0.1 ``` -After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx[esm, cjs, amd].js` (or `.min.js`). -For example, you might bundle htmx with some extensions and project-specific code. - -### Webpack - -If you are using [webpack](https://webpack.js.org) to manage your javascript: - -* Install `htmx.org` via your favourite package manager (like npm or yarn) -* Add the import to your `index.js` +After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx[.esm, .cjs, .amd].js` (or `.min.js`). +In the simplest case all you need to do is to add this import to your entry point (like `index.js`) ```js import 'htmx.org'; ``` -If you want to use the global `htmx` variable (recommended), you need to inject it to the window scope: +However, you will probably need the global `htmx` variable, which gives your code access to methods like +`htmx.onLoad` and allow you to use npm-installed htmx plugins. You can use one of the solutions following solutions +to achieve this. -* Create a custom JS file -* Import this file to your `index.js` (below the import from step 2) -```js -import 'path/to/my_custom.js'; -``` +#### Global variable -* Then add this code to the file: +Create a local `htmx.js` with the following content: ```js import htmx from "htmx.org/dist/htmx.esm"; window.htmx = htmx; ``` -* Finally, rebuild your bundle +Import this file in your entry point (like `index.js`): -### Vite +```js +import './htmx.js'; -If you are using [Vite](https://vitejs.dev) to manage your javascript: +// now you can import extensions +import 'htmx-ext-debug/debug.js'; +// and use htmx methods +htmx.onLoad((content) => { + console.log('Hello') +}); +``` + +#### Webpack -1. Install `htmx.org` via your favourite package manager (like npm or yarn) +If you are using [webpack](https://webpack.js.org) to manage your javascript, the better option is +to add the following to your `webpack.config.js` -2. Load htmx +```js +import webpack from 'webpack'; - You will probably want to use the global htmx variable so that you can access methods like -`htmx.onLoad` or use npm-installed plugins that expect `htmx` global to be present. - - To achieve this you need to inject `htmx` into the window scope. +/** @type {import("webpack").Configuration} */ +export default { + entry: './src/index.js', + //[...] + plugins: [ + new webpack.ProvidePlugin({ + htmx: 'htmx.org/dist/htmx.esm', + }), + ], +}; +``` - * Add the following to your `vite.config.js`: +#### Vite - ```js - export default defineConfig({ - build: { - plugins: [ - inject({ - htmx: 'htmx.org/dist/htmx.esm', - }), - ], - }, - }) - ``` +If you are using [Vite](https://vitejs.dev) to manage your javascript, the better option is +to add the following to your [vite.config.js](https://vitejs.dev/guide/backend-integration.html): - Alternatively, if you don't need the `htmx` global variable then add the following to - your entry point [main.js file](https://vitejs.dev/guide/backend-integration.html): - ```js - import 'htmx.org'; - ``` +```js +import inject from '@rollup/plugin-inject'; + +export default defineConfig({ + build: { + //[...] + plugins: [ + inject({ + htmx: 'htmx.org/dist/htmx.esm', + }), + ], + }, +}) +``` -3. Finally, rebuild your bundle +Finally, rebuild your bundle. ## AJAX From 9d8ca9448248d10613116eeac54845f165f0a957 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Wi=C5=9Bniowski?= Date: Fri, 28 Jun 2024 08:25:39 +0200 Subject: [PATCH 4/6] Use dist/htmx.esm.js as the module entry point; Update docs to reflect the change --- www/content/docs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index 328337ebd..c0605d9ff 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -169,7 +169,7 @@ to achieve this. Create a local `htmx.js` with the following content: ```js -import htmx from "htmx.org/dist/htmx.esm"; +import htmx from "htmx.org"; window.htmx = htmx; ``` @@ -200,7 +200,7 @@ export default { //[...] plugins: [ new webpack.ProvidePlugin({ - htmx: 'htmx.org/dist/htmx.esm', + htmx: 'htmx.org', }), ], }; @@ -219,7 +219,7 @@ export default defineConfig({ //[...] plugins: [ inject({ - htmx: 'htmx.org/dist/htmx.esm', + htmx: 'htmx.org', }), ], }, From fc272ef75fbf40e765f5941f011d7dcfaca44bec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Wi=C5=9Bniowski?= Date: Fri, 12 Jul 2024 08:27:43 +0200 Subject: [PATCH 5/6] Fix Vite's defineConfig example in docs --- www/content/docs.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index c0605d9ff..eb6a5d785 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -215,14 +215,12 @@ to add the following to your [vite.config.js](https://vitejs.dev/guide/backend-i import inject from '@rollup/plugin-inject'; export default defineConfig({ - build: { - //[...] - plugins: [ - inject({ - htmx: 'htmx.org', - }), - ], - }, + build: {...}, + plugins: [ + inject({ + htmx: 'htmx.org', + }), + ], }) ``` From 235cbc9555fcbef3f17f351b784bb4ae8f317c07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Wi=C5=9Bniowski?= Date: Tue, 29 Oct 2024 09:13:09 +0100 Subject: [PATCH 6/6] Update www/content/docs.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Théophile Choutri de Tarlé --- www/content/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/content/docs.md b/www/content/docs.md index eb6a5d785..1c29b603c 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -160,7 +160,7 @@ import 'htmx.org'; ``` However, you will probably need the global `htmx` variable, which gives your code access to methods like -`htmx.onLoad` and allow you to use npm-installed htmx plugins. You can use one of the solutions following solutions +`htmx.onLoad` and allow you to use npm-installed htmx plugins. You can use one of the following solutions to achieve this.