jaip-frontend

This template should help get you started developing with Vue 3 in Vite.

Recommended IDE Setup

VSCode + Volar (and disable Vetur).

Type Support for .vue Imports in TS

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need Volar to make the TypeScript language service aware of .vue types.

Customize configuration

See Vite Configuration Reference.

Subdomains

Many aspects of this project are highly dependent on the subdomain. Perhaps most importantly, the difference between the student and admin versions of the site is largely determined by whether the user is visiting the pep subdomain or the admin.pep subdomain.

In some browsers, including Chrome and Firefox, it is possible to simply use http://pep.localhost:5173/ and http://admin.pep.localhost:5173/ as the domains for the site. This requires a modification of /etc/hosts and will not work in Safari.

Specifically, a line like the following can be added to /etc/hosts, which will allow browsers to use the subdomains properly:

127.0.0.1 pep.localhost admin.pep.localhost

Environment

The .env.example file includes some values and notes that may be useful to place into a .env file. Note that when using a remote server for the API_URL, this will affect the application's environment. The prod API will use production data and return prod in the environment check that determines the URL of the login button.

Project Setup

Install nvm for managing the project node version.

Activate the pinned node version based on this project's .nvmrc file.

$ nvm use

If you do not have that node version on your local machine, nvm will say so. Use nvm install to install the pinned version.

Finally, install project depdendencies:

$ yarn install

Compile and Hot-Reload for Development

yarn dev

Type-Check, Compile and Minify for Production

yarn build

Run Headed Component Tests with Cypress Component Testing

yarn test:unit:dev # or `yarn test:unit` for headless testing

Run End-to-End Tests with Cypress

yarn test:e2e:dev

This runs the end-to-end tests against the Vite development server. It is much faster than the production build.

But it's still recommended to test the production build with test:e2e before deploying (e.g. in CI environments):

yarn build
yarn test:e2e

Lint with ESLint

yarn lint

Logging

Logs are sent from the frontend to the backend using the Beacon API in order to send non-blocking requests to the server. Log events must include and eventtype and event_description. The remaining fields necessary for Captain's Logging will be added by the backend. Additional fields can be added as needed.

Frontend logging works locally as well as in the TEST and PROD environments. In the ephemeral cluster, however, it will return 405 Method Not Allowed errors as a result of CORS issues. This does mean frontend logs will not work in the ephemeral environment.

Local docker image build

The first time you run the docker image build locally, first run:

cp nginx/nginx.conf.persistent nginx/nginx.conf

This simulates the repo setup that takes place during the build app image job in our CICD setup.

Collections

The JSTOR Access in Prison platform now includes content that is distinct from the content available on JSTOR. The content is divided into collections. The current pilot includes a single collection for reentry content.

The collections system provides structured access to curated content through the custom_content API endpoints.

Current Collections

• reentry: Educational and reentry resources (primary collection)

Adding New Material to Reentry Collection

New material is added to the reentry collection primarily via jaip-backend repository, thumbnails for the collection items are located in ./public/thumbnails.

Thumbnail Creation:

• Use the thumbnail.zsh script in this repository to generate any new thumbnails once the collection materials have been added to S3.

Limitations

We try to make this software available on as many devices as possible. That often means being prepared to work on devices that don't have access to modern browser features like structuredClone or

JavaScript

structuredClone

PDF.js does not work without structuredClone. This generally means that browsers more than ~4 years old will not be supported. For now, we offer a page image viewer as an alternative, but as older browsers fade out, we will migrate away from that option.

CSS

Some devices we need to support do not allow access to certain CSS properties or units.

Viewport Units

Viewport width and height properties, including all their various addons, are not available on all devices. The following fallback pattern is suggested for any CSS changes involving viewport heights or widths:

1. %
2. vh
3. dvh

In some cases, it may also be helpful to add a min-height or min-width property, typically using px units to ensure that a particular element is not only visible but appearing at a usable size.