amphora-html 5.1.0 → 5.2.0

package/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: ['**']
+    tags: ['**']
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [18, 20]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+

package/.github/workflows/push.yml

@@ -1,26 +1,39 @@
-on: push
 name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [master]
+
 jobs:
-  filterBranch:
-    name: Filter branch
+  deploy-docs:
+    name: Deploy docs
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
-    - uses: actions/checkout@master
-    - name: Filter branch
-      uses: actions/bin/filter@master
-      with:
-        args: branch master
-    - name: Install
-      uses: actions/npm@master
-      with:
-        args: install --prefix ./website
-    - name: Update version
-      uses: clay/docusaurus-github-action@master
-      with:
-        args: version
-    - name: Build and push docs
-      uses: clay/docusaurus-github-action@master
-      env:
-        DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
-      with:
-        args: deploy
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '16'
+
+      - name: Install website dependencies
+        run: npm install
+        working-directory: website
+
+      - name: Update Docusaurus version
+        run: npm run version
+        working-directory: website
+
+      - name: Build Docusaurus site
+        run: npm run build
+        working-directory: website
+
+      - name: Publish docs to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./website/build/amphora-html

package/lib/media.js

@@ -6,9 +6,10 @@ const _ = require('lodash'),
   bluebird = require('bluebird'),
   setup = require('./setup'),
   styleguide = require('./styleguide'),
-  url = require('url'),
   STYLE_TAG = 'style',
   SCRIPT_TAG = 'scripts',
+  MODULE_SCRIPT_TAG = 'module',
+  MODULEPRELOAD_TAG = 'modulepreload',
   MEDIA_DIRECTORY = path.join(process.cwd(), 'public');
 
 /**
@@ -147,15 +148,35 @@ function appendMediaToBottom(scripts, html) {
   return splice(html, index, scripts);
 }
 
-function injectTags(fileArray, site, tag) {
+/**
+ * Build inline <link>/<script> tags for an array of asset paths. Used by edit
+ * mode (where assets are loaded individually rather than bundled) and by the
+ * Vite ESM pipeline (module / modulepreload).
+ *
+ * @param {string[]} fileArray  asset paths
+ * @param {string} tag  one of STYLE_TAG, SCRIPT_TAG, MODULE_SCRIPT_TAG, MODULEPRELOAD_TAG
+ * @returns {Promise<string>}  newline-joined tag string
+ */
+function injectTags(fileArray, tag) {
   var buster = module.exports.cacheBuster ? `?version=${module.exports.cacheBuster}` : '';
+  // When omitCacheBusterOnModules is enabled, content-hashed ESM files omit the
+  // ?version= query string — the hash in the filename already provides cache busting.
+  // Defaults to false so existing deployments are unaffected.
+  var moduleBuster = module.exports.omitCacheBusterOnModules ? '' : buster;
 
   return bluebird.resolve(_.map(fileArray, function (file) {
     if (tag === STYLE_TAG) {
       return `<link rel="stylesheet" type="text/css" href="${file}${buster}">`;
-    } else {
-      return `<script type="text/javascript" src="${file}${buster}"></script>`;
+    } else if (tag === MODULE_SCRIPT_TAG) {
+      return `<script type="module" src="${file}${moduleBuster}"></script>`;
+    } else if (tag === MODULEPRELOAD_TAG) {
+      // <link rel="modulepreload"> tells the browser to fetch ESM scripts early,
+      // during HTML parsing, before reaching the <script> tags at </body>.
+      return `<link rel="modulepreload" href="${file}${moduleBuster}">`;
     }
+
+    // Default: classic <script src=...> for SCRIPT_TAG and any other value.
+    return `<script type="text/javascript" src="${file}${buster}"></script>`;
   }).join('\n'));
 }
 
@@ -313,6 +334,14 @@ function configure(options, cacheBuster = '') {
   if (options && _.isObject(options)) {
     module.exports.editStylesTags = options.styles || false;
     module.exports.editScriptsTags = options.scripts || false;
+    // modulepreload: when true, <link rel="modulepreload"> hints are injected
+    // into <head> for ESM scripts, and ?version= is omitted from module URLs
+    // since content-hashed filenames already provide cache busting.
+    // Opt-in only — defaults to false for backwards compatibility.
+    if (options.modulepreload !== undefined) {
+      module.exports.modulepreload = !!options.modulepreload;
+      module.exports.omitCacheBusterOnModules = !!options.modulepreload;
+    }
   } else {
     module.exports.editStylesTags = options;
     module.exports.editScriptsTags = options;
@@ -332,6 +361,7 @@ function configure(options, cacheBuster = '') {
  * @param  {Object} state
  * @return {Function}
  */
+/* eslint-disable complexity */
 function injectScriptsAndStyles(state) {
   const { locals } = state;
 
@@ -347,24 +377,50 @@ function injectScriptsAndStyles(state) {
     mediaMap = module.exports.getMediaMap(state);
 
     // allow site to change the media map before applying it
+    // Expose rendered component names so resolveMedia can do per-component script resolution
+    // (e.g. pack-next manifest lookup) without needing a reference to the full state object.
+    locals._components = state._components;
     if (setup.resolveMedia) mediaMap = setup.resolveMedia(mediaMap, locals) || mediaMap;
 
+    // moduleScripts: ESM scripts (e.g. from esbuild pack-next) that need type="module"
+    const moduleScriptFiles = mediaMap.moduleScripts || [];
+
+    mediaMap.moduleScripts = moduleScriptFiles.length
+      ? injectTags(moduleScriptFiles, MODULE_SCRIPT_TAG)
+      : bluebird.resolve(false);
+
+    // modulePreloads: <link rel="modulepreload"> hints for <head>.
+    // Only active when configure({ modulepreload: true }) has been called — opt-in so
+    // sites not using the clay build pipeline are completely unaffected.
+    const modulePreloadFiles = module.exports.modulepreload
+      ? mediaMap.modulePreloads || []
+      : [];
+
+    mediaMap.modulePreloads = modulePreloadFiles.length
+      ? injectTags(modulePreloadFiles, MODULEPRELOAD_TAG)
+      : bluebird.resolve(false);
+
     if (!locals.edit) {
       mediaMap.styles = combineFileContents(mediaMap.styles, 'public/css', '/css/', STYLE_TAG);
       mediaMap.scripts = combineFileContents(mediaMap.scripts, 'public/js', '/js/', SCRIPT_TAG);
     } else {
-      mediaMap.styles = module.exports.editStylesTags ? injectTags(mediaMap.styles, locals.site, STYLE_TAG) : combineFileContents(mediaMap.styles, 'public/css', '/css/', STYLE_TAG);
-      mediaMap.scripts = module.exports.editScriptsTags ? injectTags(mediaMap.scripts, locals.site, SCRIPT_TAG) : combineFileContents(mediaMap.scripts, 'public/js', '/js/', SCRIPT_TAG);
+      mediaMap.styles = module.exports.editStylesTags ? injectTags(mediaMap.styles, STYLE_TAG) : combineFileContents(mediaMap.styles, 'public/css', '/css/', STYLE_TAG);
+      mediaMap.scripts = module.exports.editScriptsTags ? injectTags(mediaMap.scripts, SCRIPT_TAG) : combineFileContents(mediaMap.scripts, 'public/js', '/js/', SCRIPT_TAG);
     }
 
     return bluebird.props(mediaMap)
       .then(combinedFiles => {
+        // modulepreload hints go first in <head>, before CSS, so the browser can
+        // start fetching ESM scripts at the earliest possible moment.
+        html = combinedFiles.modulePreloads ? appendMediaToTop(combinedFiles.modulePreloads, html) : html;
         html = combinedFiles.styles ? appendMediaToTop(combinedFiles.styles, html) : html; // If there are styles, append them
+        html = combinedFiles.moduleScripts ? appendMediaToBottom(combinedFiles.moduleScripts, html) : html; // ESM module scripts (type="module")
         html = combinedFiles.scripts ? appendMediaToBottom(combinedFiles.scripts, html) : html; // If there are scripts, append them
         return html; // Return the compiled HTML
       });
   };
 }
+/* eslint-enable complexity */
 
 module.exports.injectScriptsAndStyles = injectScriptsAndStyles;
 module.exports.getMediaMap = getMediaMap;
@@ -372,6 +428,10 @@ module.exports.cacheBuster = '';
 module.exports.configure = configure;
 module.exports.editStylesTags = false;
 module.exports.editScriptsTags = false;
+// Opt-in flags for the clay build (esbuild) pipeline.
+// Enable via configure({ modulepreload: true }).
+module.exports.modulepreload = false;
+module.exports.omitCacheBusterOnModules = false;
 
 // For testing
 module.exports.getScriptFiles = getScriptFiles;

package/lib/render.js

@@ -38,6 +38,9 @@ function applyRenderHooks(ref, data, locals) {
  *
  * @param {String} ref
  * @param {Object} locals
+ * @param {Object} res
+ * @param {String} self  Clay ref of the component being rendered, e.g.
+ *   "site.com/_components/article/instances/foo"
  * @returns {Function}
  */
 function applyPostRenderHooks(ref, locals, res, self) {
@@ -182,8 +185,12 @@ function logTime(hrStart, msg, route) {
   };
 }
 
-function configure({ editAssetTags, cacheBuster }) {
-  mediaService.configure(editAssetTags, cacheBuster);
+function configure({ editAssetTags, cacheBuster, modulepreload }) {
+  const mediaOptions = editAssetTags && typeof editAssetTags === 'object'
+    ? Object.assign({}, editAssetTags, modulepreload !== undefined ? { modulepreload } : {})
+    : editAssetTags;
+
+  mediaService.configure(mediaOptions, cacheBuster);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amphora-html",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "An HTML renderer for component data",
   "main": "index.js",
   "scripts": {

package/.circleci/config.yml

@@ -1,44 +0,0 @@
-version: 2
-
-# Set defaults to reuse
-defaults: &defaults
-  working_directory: ~/repo
-  docker:
-    - image: circleci/node:8.10.0
-
-jobs:
-  test:
-    <<: *defaults
-    steps:
-      - checkout
-
-      - restore_cache:
-          keys:
-            - v2-dependencies-{{ checksum "package.json" }}
-            # fallback to using the latest cache if no exact match is found
-            - v2-dependencies-
-
-      - run: npm install
-      - run:
-          name: Run tests
-          command: npm test
-      - run:
-          name: Send to Coveralls
-          command: cat coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js
-      - save_cache:
-          paths:
-            - node_modules
-          key: v2-dependencies-{{ checksum "package.json" }}
-
-      - persist_to_workspace:
-          root: ~/repo
-          paths: .
-
-workflows:
-  version: 2
-  test-deploy:
-    jobs:
-      - test:
-          filters:
-            tags:
-              only: /^v[0-9]+\.[0-9]+\.[0-9]+/