amphora-html 6.0.0-dev.0 → 6.0.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: [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/lib/media.js

@@ -6,12 +6,10 @@ const _ = require('lodash'),
   bluebird = require('bluebird'),
   setup = require('./setup'),
   styleguide = require('./styleguide'),
-  url = require('url'),
   STYLE_TAG = 'style',
   SCRIPT_TAG = 'scripts',
-  ASYNC_SCRIPT_TAG = 'async',
-  DEFER_SCRIPT_TAG = 'defer',
-  ASYNC_DEFER_SCRIPT_TAG = 'async-defer',
+  MODULE_SCRIPT_TAG = 'module',
+  MODULEPRELOAD_TAG = 'modulepreload',
   MEDIA_DIRECTORY = path.join(process.cwd(), 'public');
 
 /**
@@ -150,47 +148,36 @@ 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 if (tag === ASYNC_SCRIPT_TAG) {
-      return `<script async src="${file}" type="text/javascript"></script>`;
-    } else if (tag === DEFER_SCRIPT_TAG) {
-      return `<script defer src="${file}" type="text/javascript"></script>`;
-    } else if (tag === ASYNC_DEFER_SCRIPT_TAG) {
-      return `<script async defer src="${file}" type="text/javascript"></script>`;
-    } 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}">`;
     }
-  }).join('\n'));
-}
 
-/**
- * Filter the components rendered in this request, removing Webpack-managed
- * assets so that we can fall back on Browserify.
- *
- * @param {Object} state - Amphora render state.
- * @returns {string[]} - A list of components not available through Webpack.
- */
-function filterManifestComponents(state) {
-  const site = state.locals.site,
-    assetDir = site && site.assetDir || MEDIA_DIRECTORY,
-    manifestName = site && site.manifestName || 'assets-manifest.json',
-    manifestFile = path.resolve(path.join(assetDir, manifestName));
-  let manifest;
-
-  try {
-    manifest = files.tryRequire(manifestFile);
-  } catch (err) {
-    return state._components;
-  }
-
-
-  return state._components
-    .filter(componentName => !manifest.hasOwnProperty(`${ componentName }.js`));
+    // Default: classic <script src=...> for SCRIPT_TAG and any other value.
+    return `<script type="text/javascript" src="${file}${buster}"></script>`;
+  }).join('\n'));
 }
 
 /**
@@ -202,7 +189,6 @@ function getMediaMap(state) {
   return {
     styles: module.exports.getStyleFiles(state),
     scripts: module.exports.getScriptFiles(state),
-    manifestAssets: module.exports.getManifestAssets(state)
   };
 }
 
@@ -303,7 +289,7 @@ function getScriptFiles(state) {
     assetPath = site && site.assetPath || '',
     assetHost = site && site.assetHost || '';
 
-  return filterManifestComponents(state)
+  return state._components
     .reduce((prev, name) => {
       prev.push(
         path.join(assetDir, 'js', `${name}.js`),
@@ -316,36 +302,6 @@ function getScriptFiles(state) {
     .map(pathJoin(assetHost, assetPath, assetDir));
 }
 
-/**
- * Read the asset manifest generated by the `clay pack` bundling command and
- * check for scripts which match the rendered component names. The manifest for
- * each asset lists its complete set of dependencies, so we dedupe them.
- * Webpack's runtime is added to the beginning of the list, downstream legacy
- * globals and Clay CLI's init script to the end.
- *
- * @param {Object} state - Amphora's render state.
- * @return {string[]} A list of component assets.
- */
-function getManifestAssets(state) {
-  const site = state.locals.site,
-    assetDir = site && site.assetDir || MEDIA_DIRECTORY,
-    assetHost = site && site.assetHost || '/',
-    manifestName = site && site.manifestName || 'assets-manifest.json',
-    manifestFile = path.resolve(path.join(assetDir, manifestName));
-  let manifest;
-
-  try {
-    manifest = files.tryRequire(manifestFile);
-  } catch (err) {
-    return [];
-  }
-
-  const entrypoints = _.get(manifest, 'entrypoints', []);
-  const scriptFiles = _.flatMap(entrypoints, entrypoint => _.get(entrypoint, 'assets.js', []));
-
-  return scriptFiles.map(script => url.resolve(assetHost, script));
-}
-
 /**
  * Trim the path on the file system bythe link of the
  * asset directory and then join it with either the assetHost
@@ -378,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;
@@ -397,6 +361,7 @@ function configure(options, cacheBuster = '') {
  * @param  {Object} state
  * @return {Function}
  */
+/* eslint-disable complexity */
 function injectScriptsAndStyles(state) {
   const { locals } = state;
 
@@ -412,26 +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 = !!mediaMap.manifestAssets && mediaMap.manifestAssets.length > 0
-        ? injectTags(mediaMap.manifestAssets, locals.site, SCRIPT_TAG)
-        : combineFileContents(mediaMap.scripts, 'public/js', '/js/', SCRIPT_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;
@@ -439,8 +428,11 @@ 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.getManifestAssets = getManifestAssets;
 module.exports.getScriptFiles = getScriptFiles;
 module.exports.getStyleFiles = getStyleFiles;

package/lib/media.test.js

@@ -101,7 +101,7 @@ describe(_.startCase(filename), () => {
     const fn = lib['getMediaMap'];
 
     test('accepts state with empty components', () => {
-      expect(fn(state)).toEqual({manifestAssets: [], scripts: [], styles: []});
+      expect(fn(state)).toEqual({scripts: [], styles: []});
     });
 
     test('accepts list, empty slug (non-existent components)', () => {
@@ -114,7 +114,7 @@ describe(_.startCase(filename), () => {
             _.omit(state, ['locals.site.slug'])
           )
         )
-      ).toEqual({manifestAssets: [], scripts: [], styles: []});
+      ).toEqual({scripts: [], styles: []});
     });
 
     test('accepts list and slug (non-existent components)', () => {
@@ -127,7 +127,7 @@ describe(_.startCase(filename), () => {
             state
           )
         )
-      ).toEqual({manifestAssets: [], scripts: [], styles: []});
+      ).toEqual({scripts: [], styles: []});
     });
 
     test(
@@ -151,7 +151,7 @@ describe(_.startCase(filename), () => {
               }
             )
           )
-        ).toEqual({manifestAssets: [], scripts: expectedScriptFiles, styles: []});
+        ).toEqual({scripts: expectedScriptFiles, styles: []});
       }
     );
   });
@@ -625,117 +625,6 @@ describe(_.startCase(filename), () => {
     );
   });
 
-  describe('getManifestAssets', () => {
-    const fn = lib['getManifestAssets'];
-
-    describe('constructs the correct asset URL', () => {
-      test('when assetHost is configured', () => {
-        const assetHost = 'https://assets.nymag.com';
-        const localState = {
-          locals: {
-            site: {
-              assetHost
-            }
-          },
-          _components: [
-            'a',
-            'b'
-          ]
-        };
-        const manifest = {
-          entrypoints: {
-            a: {
-              assets: {
-                js: ['/a.js']
-              }
-            },
-            b: {
-              assets: {
-                js: ['b.js']
-              }
-            }
-          }
-        };
-
-        jest.spyOn(files, 'tryRequire').mockImplementation(() => manifest);
-
-        expect(fn(localState)).toEqual([
-          `${ assetHost }/a.js`,
-          `${ assetHost }/b.js`
-        ]);
-      });
-
-      test('when assetHost is not configured', () => {
-        const localState = {
-          locals: {
-            site: {
-            }
-          },
-          _components: [
-            'a',
-            'b'
-          ]
-        };
-        const manifest = {
-          entrypoints: {
-            a: {
-              assets: {
-                js: ['/a.js']
-              }
-            },
-            b: {
-              assets: {
-                js: ['b.js']
-              }
-            }
-          }
-        };
-
-        jest.spyOn(files, 'tryRequire').mockImplementation(() => manifest);
-
-        expect(fn(localState)).toEqual([
-          '/a.js',
-          '/b.js'
-        ]);
-      });
-
-      test('without prepending assetPath', () => {
-        const localState = {
-          locals: {
-            site: {
-              assetPath: '/strategist'
-            }
-          },
-          _components: [
-            'a',
-            'b'
-          ]
-        };
-        const manifest = {
-          entrypoints: {
-            a: {
-              assets: {
-                js: ['/a.js']
-              }
-            },
-            b: {
-              assets: {
-                js: ['b.js']
-              }
-            }
-          }
-        };
-
-        jest.spyOn(files, 'tryRequire').mockImplementation(() => manifest);
-
-        expect(fn(localState)).toEqual([
-          '/a.js',
-          '/b.js'
-        ]);
-      });
-    });
-  });
-
   describe('injectScriptsAndStyles', () => {
     const fn = lib['injectScriptsAndStyles'];
 

package/lib/render.js

@@ -38,9 +38,12 @@ 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) {
+function applyPostRenderHooks(ref, locals, res, self) {
   return (html) => {
 
     // skip postRender hooks in edit mode
@@ -50,7 +53,7 @@ function applyPostRenderHooks(ref, locals) {
 
     return setup.plugins.filter((plugin) => plugin.postRender)
       .reduce((val, plugin) => {
-        return plugin.postRender(ref, html, locals);
+        return plugin.postRender(ref, html, locals, res, self);
       }, html);
   };
 }
@@ -148,7 +151,7 @@ function render(data, meta, res) {
   return applyRenderHooks(state._layoutRef || state.self, data, state.locals)
     .then(makeHtml(state))
     .then(mediaService.injectScriptsAndStyles(state))
-    .then(applyPostRenderHooks(state._layoutRef || state.self, state.locals))
+    .then(applyPostRenderHooks(state._layoutRef || state.self, state.locals, res, meta._ref))
     .then(result => {
       res.type('text/html');
       res.send(result);
@@ -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,8 +1,11 @@
 {
   "name": "amphora-html",
-  "version": "6.0.0-dev.0",
+  "version": "6.0.0",
   "description": "An HTML renderer for component data",
   "main": "index.js",
+  "engines": {
+    "node": ">=20.14.0"
+  },
   "scripts": {
     "test": "npm run eslint && npm run jest -- --coverage --no-cache",
     "eslint": "eslint --max-warnings 0 lib test",

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]+/

package/.github/workflows/push.yml

@@ -1,26 +0,0 @@
-on: push
-name: Deploy to GitHub Pages
-jobs:
-  filterBranch:
-    name: Filter branch
-    runs-on: ubuntu-latest
-    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