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/primo_explore_search_embed.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 git@github.com: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 un-styled.

---

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

There aren't always live dev instances of the websites that use bess-vue, and in cases where there are dev instances, we don't always have the ability configure them to load bess-vue from the dev CDN in order to preview changes. We can work around this limitation somewhat but making use of local overrides. Naturally, local overrides can also be used to load the local application build and other assets from the local environment. There are overrides for both local and dev-CDN previewing in browser-overrides/. For local/, in addition to the bess-vue build override, in cases where we own the stylesheet, the CSS build file is overridden as well.

For Chromium-based browsers:

• Follow these instructions for setting up local overrides, setting the override folder to either dev/ or local/ 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/lockerbox/search-boxes/catalog
  • NYUAD: https://nyuad.nyu.edu/library.html and https://guides.nyu.edu/lockerbox/search-boxes/catalog
  • NYUSH: https://guides.nyu.edu/nyushcscapstone/books and https://guides.nyu.edu/lockerbox/search-boxes/catalog
  • NYU HOME: https://globalhome.nyu.edu/

Note that symlinks are apparently not supported by Chromium local overrides. This means that dev/ and local/ can't be DRY'ed up by linking to shared assets, and similarly in the case of local/, the app.min.js builds cannot be links to dist/app.min.js but instead have to be separate, identical copies of it. There is an npm script "update-browser-overrides" which uses scripts/update-browser-overrides-app-builds.sh to update browser-overrides/local/ after a new build is created in dist/.

---

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

Using Docker Compose:

docker compose up test

---

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 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/primo_explore_search_embed.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.