University of Minnesota's webpack-based toolkit for building Primo VE customization packages.
When planning our migration from Primo to Primo VE, we discovered that VE does not support central packages in single-institution, multi-campus Alma environments. To work around this limitation, we are using a custom build tool for our Primo customization packages.
- Make sure Node.js version 18+ is installed.
- Clone this repository.
- From the project's root directory, run
npm install.
Run npm start to launch a development proxy server and preview the customization packages in the UMN Libraries production server. To preview a view, go to http://localhost:8080/discovery/search?vid={view_code} (e.g. http://localhost:8080/discovery/search?vid=01UMN_INST:TWINCITIES). If you need to modify the email template, you can preview an example at http://localhost:8080/discovery/email-template?lang=en&vid={view_code}&dirName.
Set the PROXY_TARGET environment variable to preview the customizations in a different Primo environment (e.g. PROXY_TARGET=umn.primo.exlibrisgroup.com npm start).
The color theme is generated with the primo-color-theme tool. To modify the color theme, edit src/shared/color-theme/colors.json and then run npm run color-theme. This will rebuild the src/shared/color-theme/generated-theme.css file. It's a good practice to regenerate the color theme whenever Primo VE is upgraded.
Note: The color variables defined in src/shared/color-theme/colors.js are available globally in any sass/scss file.
Run npm run build to create production-ready deployment packages. A zip file for each view will be created under dist/packages/. To deploy a package, upload its zip file in the Manage Customization Package tab in Alma (under Discovery > Manage Views > {view_code}).
This project uses Babel to compile TypeScript. Babel is a fast compiler, but it doesn't perform type checking. Run npm test:types to perform type checking on all TypeScript files using the standard tcs compiler.
Run npm run test:unit to execute the unit tests using headless Karma. The Karma configuration file is karma.config.cjs.
You could also use npm test to run type checking and unit tests in one step.
Per angular convention, unit tests (spec files) are located in the same directory as the implementation. For instance:
src/
...
foo/
foo.component.ts
foo.component.spec.ts
Note: we're now using Cypress instead of Protractor for end-to-end tests.
Run npm run test:e2e to launch the local dev server and execute the end-to-end tests. The Cypress configuration and test files are in the cypress/ directory.
If you care to use the Cypress GUI, you can launch it with npm cy:open.
The files under src/shared/ are intended to be shared across all views. Any view-specific customizations belong under src/views/. As much as possible the src/shared/components are structured to match the Primo component tree.
src
├── @types
├── shared
│ ├── color-theme
│ ├── components
│ ├── filters
│ ├── html
│ ├── img
│ └── services
└── views
├── 01UMN_INST-CROOKSTON
│ ├── html
│ └── img
├── 01UMN_INST-DULUTH
│ ├── components
│ ├── html
│ └── img
├── 01UMN_INST-MORRIS
│ ├── components
│ ├── html
│ └── img
└── 01UMN_INST-TWINCITIES
├── components
├── html
└── img
At build time, a Primo customization package is created for each view. Each view's TypeScript/JavaScript files are bundled into a single js/custom.js file, and each view's SCSS/CSS files are bundled into a single css/custom1.css file. All assets from the following directories are copied to the package as-is:
src/shared/html/src/shared/img/src/views/*/html/src/views/*/img/
Build output:
dist
├── 01UMN_INST-CROOKSTON
│ ├── css
│ ├── html
│ ├── img
│ └── js
├── 01UMN_INST-DULUTH
│ ├── css
│ ├── html
│ ├── img
│ └── js
├── 01UMN_INST-MORRIS
│ ├── css
│ ├── html
│ ├── img
│ └── js
├── 01UMN_INST-TWINCITIES
│ ├── css
│ ├── html
│ ├── img
│ └── js
└── packages
├── 01UMN_INST-CROOKSTON.zip
├── 01UMN_INST-DULUTH.zip
├── 01UMN_INST-MORRIS.zip
└── 01UMN_INST-TWINCITIES.zip
This project uses Browserslist to target JavaScript and CSS compatibility. This helps to reduce bundle bloat by omitting polyfills for unsupported browsers such as Internet Explorer 11. The targeted browsers are defined in .browserslistrc.