Bess Vue

Embed a JS search form to your Primo (new) UI in any webpage.

---

Usage

<!-- container where embeddable search will be injected -->
<div id="bess_vue_container_nyuad"></div>
<!-- ensure that the injectable element's id matches the element_id value in query string -->
<script type="text/javascript" id="bess_vue" src="https://cdn.library.nyu.edu/bess-vue/app.min.js?institution=NYUAD&element_id=bess_vue_container_nyuad">
</script>
<!-- Component comes unstyled. Optionally embed CSS. -->
<!-- NOTE: See "Project rename: primo-explore-search-embed to bess-vue" in this
           README for the reason why the previous widget name primo-explore-search-embed
           is being used for the CSS file name. -->
<link type="text/css" rel="stylesheet" href="https://cdn.library.nyu.edu/bess-vue/bess.min.css" />

---

Prerequisites

• Node 18 or higher (nvm recommended)

---

Getting started

• Install
• Run in dev server with HMR
• To preview all configurations simultaneously in the example local HTML file:
  • Build
  • Preview configurations for all institutions on one page
• To view the dev CDN build in the sample institution HTML pages: View dev CDN build in sample institution HTML pages

---

Install

git clone [email protected]:NYULibraries/bess-vue.git
cd bess-vue/
npm install

---

Build

Build for distribution. The components self-configure based on Vite mode (see Vite Modes). Currently two modes are supported: dev and prod. Builds can be run in watch mode: Rebuild on files changes

npm run build:dev
npm run build:prod
# Trigger rebuild on file changes
npm run build:dev:watch
npm run build:prod:watch

Using Docker Compose:

docker compose up build-dev
docker compose up build-prod
# Trigger rebuild on file changes
docker compose up build-dev-watch
docker compose up build-prod-watch

---

Run in dev server with HMR

npm run dev:nyu
npm run dev:nyuad
npm run dev:nyush
npm run dev:nyu-home

Using Docker Compose:

docker compose up dev-nyu
docker compose up dev-nyuad
docker compose up dev-nyush
docker compose up dev-nyu-home

---

Preview configurations for all institutions on one page

Open file index-all-institutions.html directly in a browser. This HTML page contains instances for all institution configurations on a single page, loaded from the local repo clone and styled with the public/bess.min.css stylesheet.

---

Deployments to Dev

All institutional instances of LibGuides are deployed to cdn-dev from non-master branch commits. To view live installations of these, see:

• NYU: https://dev.library.nyu.edu
• LibGuides (NYU, NYUAD, NYUSH): https://nyu.libapps.com/libguides/admin_c.php?g=276565&p=10646424 (requires login to Springshare)

For installations without a corresponding dev (e.g., NYUAD library home page, NYU Home) see "View local and dev-CDN builds in sample institution HTML pages using browser-overrides/" below

---

View local and dev-CDN builds in institution HTML pages using browser-overrides/

We can use Chrome (Chromium) local overrides to test our embedded widget in situ while developing locally. We can also if we wish use local overrides to force the web pages to load the widget from dev CDN instead of prod CDN. While this latter option has a longer feedback cycle than the former which loads from local dist/, it accommodates workflows where the developer might prefer to push to dev CDN first before testing, for whatever reason.

Note that the local overrides are stored in a directory called browser-overrides/, to avoid overloading the word "local" too much.

For Chromium-based browsers (works in Brave):

• Follow these instructions for setting up local overrides, setting the override folder to either use-local-bess/ or use-dev-bess/ in browser-overrides/: Override web content and HTTP response headers locally
• Navigate to the URLs for the institutions that currently use bess-vue:
  • NYU: https://library.nyu.edu/ and https://guides.nyu.edu/nyu-reusable-templates-and-content/search-boxes/catalog
  • NYUAD: https://nyuad.nyu.edu/library.html and https://guides.nyu.edu/nyu-reusable-templates-and-content/search-boxes/catalog
  • NYUSH: https://guides.nyu.edu/nyushcscapstone/books and https://guides.nyu.edu/nyu-reusable-templates-and-content/search-boxes/catalog
  • NYU HOME: https://globalhome.nyu.edu/

Note that symlinks are apparently not supported by Chromium local overrides. This means that user-local-bess/ and use-dev-bess/ can't be DRY'ed up by symlinking to shared assets, and similarly in the case of use-local-bess/, the app.min.js "longurl" builds cannot be links to dist/app.min.js, but instead have to be separate, identical copies of it.

The scripts/update-browser-overrides.js script can be used to update all the files in browser-overrides/. Note that in order to update globalhome.nyu.edu, you must first log in using your NYU credentials and then copy the session cookie from Developer Tools and set the SESSION_COOKIE environment variable to it when running the script. If SESSION_COOKIE is not provided, the script will first issue a warning that globalhome.nyu.edu is being skipped and it will then update all the other browser overrides.

This script is not foolproof. Changes in the structure of the websites/pages can break the script of cause it to produce non-working overrides. When in doubt, create the overrides manually and then check them into the repo, and if possible, update the script.

Example: build a local prod version of bess-vue and update_browser-overrides/_:

npm run build:prod && SESSION_COOKIE=<cookie> node scripts/update-browser-overrides.js

Note that scripts/update-browser-overrides.js needs to be run after every build because the new app.min.js needs to be copied into the overrides directories.

---

ESLint

Fix ESLint errors

To fix all ESLint errors in files for which we enforce ESLint rules:

npm run eslint:fix

Using Docker Compose:

docker compose up eslint-fix

---

Tests

npm run test

Update vitest snapshots:

npm run test:update-snapshots

Using Docker Compose:

docker compose up test

Update vitest snapshots:

docker compose up test-update-snapshots

---

References

• Vite
  • Uses rollup.js for bundling
• Vitest
• Vue.js

---

Caveats

Do not put <style> tags in SFCs

• vite injects a <style> tag into the HTML containing the compiled CSS from the Vue SFCs, which causes no problems when developing locally w/ HMR or viewing the embedded widgets in index-all-institutions.html, but when embedding the widget in a web page that does not opt to use the styles from the project, this injected <style> tag can override the intended styles from that web page's stylesheets and <style> tags.
• This injection happens in both development and production mode. rollupOptions.output.assetFileNames in vite.config.js ensures the creation of the CSS file in dist/, but does not suppress the injection of the <style> tag. There does not appear to be any build option for turning off injection. The solution is to put all CSS into public/bess.min.css, which is effectively copied directly into dist/.
• TODO: See if this feature can be used to achieve what we want: Disabling CSS injection into the page

HMR and --watch of vite build might not work on some machines and in some Docker containers

• HMR and --watch might work on one Mac running one version of MacOS but not work on another Mac with different hardware running another version of MacOS. This is likely due to bugs in chokidar, which is the file watcher used by rollup.js (which Vite uses for bundling).
• There are many bug tickets in the vite, rollup, and chokidar projects. Some examples:
  • vite
    • Vite HMR not working . Changing code does not reflect on page until restart vite server #16284
  • rollup.js
    • Rollup build --watch not works on docker with Vite #5331
  • chokidar
    • Add events not fired for external drives on MacOS + Docker #1014
    • Chokidar doesn't notice changes inside Docker #1051
    • Not Detecting New Files on External Drive in macOS #1296
    • Resource starved CPU prevents ready from happening #873
• Workarounds
  • In the terminal running the HMR dev server, hit "R" and then enter.
  • For vite build --watch scripts, re-run the script of re-run the Docker Compose service. Alternatively, can use a file watcher like Facebook's Watchman external to the project to watch application code files and re-run the build.

Must use Node 18 in Dockerfile due to npm install error in Docker: "npm ERR! network request to https://registry.npmjs.org/[WHATEVER] failed"

• There are many open bug tickets in npm dealing with this error. Here's one: [BUG] npm install will randomly hang forever and cannot be closed when this occurs #4028
• This bug has only occurred in this project in Docker, so we don't require an "engines" field in package.json setting Node to version 18.

browser-overrides/ are not automatically kept up to date

• The browser-overrides/ files should not be considered authoritative. We do not currently have an automated process for updating them. They may break or become stale at any time.
• The globalhome.nyu.edu override in particular can break completely at any moment because the web page currently loads chunked assets whose hashes change. Note that globalhome injects the <script> tag for bess-vue into the HTML via JavaScript in the js/chunk-[HASH].js file. When updating the override, search for "cdn.library.nyu.edu" in the new chunk file and change it to "cdn-dev.library.nyu.edu". Delete the <script> tag in the downloaded HTML and also delete the old chunk file. As with any of the overrides, this procedure could become obsolete at any time.

Setting production mode

• The package.json scripts use both NODE_ENV=production and --mode=production vite and vitest flags. In theory, only the flag should be necessary, as it is supposed to override the NODE_ENV var, and the vitest --mode flag is supposed to override the vite --mode flag. In practice, these rules don't always seem to hold. Also, there was at least one bug that caused issues when trying to set import.meta.env.PROD dynamically: [🐞BUG]: import.meta.env.PROD has the wrong value, even if stubbed. #5525. This bug was fixed in 1.5.1, but until we are sure everything has stabilized and that we understand exactly how it all works, we err on the side of caution.

---

Project rename: primo-explore-search-embed to bess-vue

This project was renamed bess-vue in 10/2022. The original name for this project was primo-explore-search-embed, which could at times cause a little confusion given it shared a prefix with the Primo customization packages. Internally the project/widget was referred to as BESS, so a decision was made to make this the official name. Note that there is one reference which was not changed - the name of the compiled CSS file. The HTML of the websites that have already embedded this widget and are linking to the CSS file cannot easily be changed by us.

Old stylesheet retired

The original stylesheet primo_explore_search_embed.min.css was replaced by the bess.min.css in October 2024. The old stylesheet has been deleted from the repo but the last commit containing it is tagged: archived_primo_explore_search_embed.min.css.