@drevops/axel 0.2.0 → 0.3.0

package/README.md

@@ -16,6 +16,8 @@
 ![LICENSE](https://img.shields.io/github/license/drevops/axel)
 ![Renovate](https://img.shields.io/badge/renovate-enabled-green?logo=renovatebot)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/drevops/axel/badge)](https://scorecard.dev/viewer/?uri=github.com/drevops/axel)
+[![npm](https://img.shields.io/npm/v/@drevops/axel)](https://www.npmjs.com/package/@drevops/axel)
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@drevops/axel/badge)](https://www.jsdelivr.com/package/npm/@drevops/axel)
 
 </div>
 
@@ -164,7 +166,7 @@ Enhanced Measurement covers events Axel doesn't send, such as scrolls, site sear
 
 ## 📦 Installation
 
-Every [release](https://github.com/drevops/axel/releases/latest) attaches 1 ready-made bundle per setup. The [`@drevops/axel`](https://www.npmjs.com/package/@drevops/axel) package on npm holds the same bundles in its `build/` folder. Pick the bundle that matches how your site starts scripts and where your events go:
+Axel ships 1 ready-made bundle per setup. Pick the bundle that matches how your site starts scripts and where your events go:
 
 | Bundle                  | Starts                                   | Sends events to                                  |
 |-------------------------|------------------------------------------|--------------------------------------------------|
@@ -178,41 +180,80 @@ Every [release](https://github.com/drevops/axel/releases/latest) attaches 1 read
 
 Each bundle also comes minified, such as `axel.gtm.min.js`. A bundle holds only its own adapter, so `axel.gtm.min.js` carries no Google tag code.
 
-### Plain page
+### Where to get the bundles
 
-Add the bundle to your pages:
+Load the bundles from [jsDelivr](https://www.jsdelivr.com/package/npm/@drevops/axel), which serves every file of every release:
 
-```html
-<script src="/path/to/axel.gtm.min.js"></script>
+```text
+https://cdn.jsdelivr.net/npm/@drevops/axel@VERSION/dist/FILE
 ```
 
-The script starts tracking as soon as it loads. Its listeners sit on `document`, so it can load in `<head>` before the rest of the page. To change the defaults, see [Settings](#settings).
+The same files are in the `dist/` folder of the [`@drevops/axel`](https://www.npmjs.com/package/@drevops/axel) npm package, and in the assets of each [GitHub release](https://github.com/drevops/axel/releases/latest).
+
+Pin an exact version such as `0.3.0`. A range such as `@0` or `@latest` serves a different file after the next release, so its Subresource Integrity hash stops matching and the browser blocks the script. The notes of each release list the jsDelivr URL and hash of every bundle, plus a ready-made `<script>` tag. [`SECURITY.md`](SECURITY.md#verify-a-bundle) explains how to verify a file you downloaded.
 
-To load the bundle from a CDN, such as jsDelivr serving the npm package, add its Subresource Integrity hash. The browser then refuses to run a file that differs from the release:
+### Plain page
+
+To load the bundle from jsDelivr, add it with its Subresource Integrity hash. The browser then refuses to run a file that differs from the release:
 
 ```html
 <script
-  src="https://cdn.jsdelivr.net/npm/@drevops/axel@VERSION/build/axel.gtm.min.js"
+  src="https://cdn.jsdelivr.net/npm/@drevops/axel@VERSION/dist/axel.gtm.min.js"
   integrity="sha384-HASH"
   crossorigin="anonymous"
 ></script>
 ```
 
-Replace `VERSION` with a release version such as `0.1.1`. Replace `sha384-HASH` with the bundle's hash from that release's notes.
+Replace `VERSION` with a release version such as `0.3.0`. Replace `sha384-HASH` with the bundle's hash from that release's notes.
+
+To serve the bundle from your own site, copy it from `node_modules/@drevops/axel/dist/` after `npm install @drevops/axel`, or from the GitHub release. Then add it to your pages:
+
+```html
+<script src="/path/to/axel.gtm.min.js"></script>
+```
+
+The script starts tracking as soon as it loads. Its listeners sit on `document`, so it can load in `<head>` before the rest of the page. To change the defaults, see [Settings](#settings).
 
 ### Drupal
 
-Define a library that loads a Drupal bundle:
+To load the bundle from jsDelivr, define a library in your module or theme that points at the CDN, with the bundle's hash:
 
 ```yaml
 axel:
   js:
-    js/axel.drupal.gtm.min.js: { minified: true }
+    https://cdn.jsdelivr.net/npm/@drevops/axel@VERSION/dist/axel.drupal.gtm.min.js:
+      type: external
+      minified: true
+      attributes:
+        integrity: sha384-HASH
+        crossorigin: anonymous
   dependencies:
     - core/drupal
     - core/drupalSettings
 ```
 
+To serve the bundle from your own site instead, install it with Composer. [Asset Packagist](https://asset-packagist.org) offers npm packages as Composer packages, and `@drevops/axel` is `npm-asset/drevops--axel` there. To install it into `web/libraries`:
+
+1. Add Asset Packagist as a repository and require the package:
+
+    ```bash
+    composer config repositories.asset-packagist composer https://asset-packagist.org
+    composer require oomphinc/composer-installers-extender npm-asset/drevops--axel
+    ```
+
+2. In `composer.json`, add `npm-asset` to `extra.installer-types` and add `"type:npm-asset"` to the `web/libraries/{$name}` entry in `extra.installer-paths`. Then run `composer install`. The bundles land in `web/libraries/drevops--axel/dist/`.
+
+3. Define a library in your module or theme that loads a Drupal bundle:
+
+    ```yaml
+    axel:
+      js:
+        /libraries/drevops--axel/dist/axel.drupal.gtm.min.js: { minified: true }
+      dependencies:
+        - core/drupal
+        - core/drupalSettings
+    ```
+
 The bundle registers the `axel` behavior. The behavior starts tracking when it first attaches and reads its settings from `drupalSettings.axel`. Later attaches, such as after an AJAX request, change nothing.
 
 ### ES module

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@drevops/axel",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Turns clicks and form interactions on elements marked with data-axel-* attributes into analytics events.",
     "license": "MIT",
     "author": {
@@ -16,14 +16,16 @@
     "homepage": "https://github.com/drevops/axel#readme",
     "bugs": "https://github.com/drevops/axel/issues",
     "type": "module",
-    "main": "build/axel.esm.js",
-    "module": "build/axel.esm.js",
+    "main": "dist/axel.esm.js",
+    "module": "dist/axel.esm.js",
     "exports": {
-        ".": "./build/axel.esm.js",
-        "./build/*": "./build/*"
+        ".": "./dist/axel.esm.js",
+        "./dist/*": "./dist/*"
     },
+    "jsdelivr": "dist/axel.gtm.min.js",
+    "unpkg": "dist/axel.gtm.min.js",
     "files": [
-        "build",
+        "dist",
         "src"
     ],
     "publishConfig": {
@@ -42,7 +44,7 @@
         "test-coverage": "vitest run --coverage",
         "pretest-functional": "npm run build",
         "test-functional": "playwright test",
-        "reset": "rm -Rf node_modules build .logs"
+        "reset": "rm -Rf node_modules dist .logs"
     },
     "engines": {
         "npm": ">=10",

package/build/checksums.txt

@@ -1,13 +0,0 @@
-91e90bde9c2e2480c37cf0c35356c387f24f11ffdbe74012a4359eda2a98afd8  axel.drupal.gtag.js
-0a95adb6e21257f20b079de967b90bcad0f61d8c1f00d9b70d2bc12ecd54cf38  axel.drupal.gtag.min.js
-91f32822f91b94b0d6f9d9652d4f3cbb70a2f62a501851d72b9a9be1fcfa1605  axel.drupal.gtm.js
-96a5afa7aaf61ca1d31d3339a64027c3329e4fa105c79407c7676e5b803bcf40  axel.drupal.gtm.min.js
-93cf10260ee54462801f61f0286468378c7bb0ea08947aadfa966fdb41428517  axel.drupal.js
-7db393905da736bfc144b14fde3f566519960324baf40d08c5142d5e55cb2823  axel.drupal.min.js
-8c486331fbf9b8229250e07582e2ed84be9ca44254e34685b25aec96407ed3f7  axel.esm.js
-6a408e47149b8faea44e2c2d5e2b126175810a9ef30ec58131bee7fab14b7754  axel.gtag.js
-450a4ec7f98284332ca8008a6185be466181e898ef5690bcac539156508bea7f  axel.gtag.min.js
-fa392146d502c0288fee88c005332092c6ceca4e65fdd8d4711e724f32a9c6a6  axel.gtm.js
-602587e126909cd0acfcf212d2568257f39ac4ccaab7f9b843f5022d988b9e87  axel.gtm.min.js
-2dca0071297b0ce4684baa8301a9927434fc663fe3c5353db4605a7e4f4c0354  axel.js
-e5e2d976430559760b57b872c01598f5d4b1a45f37f85de8951068031e7a3a7b  axel.min.js