Digital Collections v2 (DCv2) is a UI application for discovering and interacting with Collections and Works in NUL's repository.
- NextJS React JS fullstack framework
- TypeScript for type safety
- Radix UI A library of React primitives for accessibility and modular development
- Stitches.dev CSS in JS
- IIIF Research APIs and Specs our data conforms to for open access.
- AWS Amplify Hosting environment
- OpenSearch Search index
The following dependencies should be "pinned" or held behind @latest
versions
@elastic/elasticsearch
: To match the version ofOpenSearch
our app uses.swiper
@honeybadger-io/js
@iiif/presentation-3
Install dependencies and run a NextJS development server:
npm install
npm run dev
Open http://devbox.library.northwestern.edu:3000 in your browser.
Open a remote SSH dev environment connection in VSCode.
cd
into the dc-nextjs
repository
-
Open a new terminal.
-
Make sure port 3000 is open by running
sg show
. If you don't see port 3000, runsg open all 3000
. View more in AWS convenience scripts. -
Temporarily change the following line in (
dc-nextjs/server.js
):
// Change
const hostname = "devbox.library.northwestern.edu";
// ...to
const hostname = "localhost";
Install dependencies
npm install
npm run dev
And now open your AWS dev environment URL (Northwestern developers only).
Commits (via merges) into the deploy/staging
branch will trigger a build in AWS Amplify to the staging environment.
https://dc.rdc-staging.library.northwestern.edu/
Commits prefaced with preview/branch-name-here
will deploy to a preview branch. The URL will be available within AWS Amplify. This is useful for sharing the feature with staff/users as a preview before committing to staging.
Commits (via merges) into the main
branch will trigger a build in AWS Amplify to the production environment.
https://dc.library.northwestern.edu/
The application makes network requests against the DC API v2 to access repository data. By default, all metadata is returned in the application. Authenticated content's media (image/audio/video) will be protected and obscured from public access.
Behind the scenes, DC API v2 is using OpenSearch v 1.2
or Elasticsearch v 7.17
. (For documentation references). Network request urls with ?as=iiif
will return data in the shape of a IIIF manifest.
OpenSearch's data can be accessed directly via Kibana by executing the following commands:
export AWS_PROFILE=staging
aws-adfs login --profile $AWS_PROFILE
es-proxy
The API supports both POST for searching and GET for Work and Collection items.
The API endpoint is an environment variable which is accessed in a local dev environment via the miscellany
Git repo.
There are no pre-commit hooks, however deploy CI will run a Prettier check on all files to ensure code quality. It's recommended to:
- Install the Prettier VSCode extension
- Enable the "Format on Save" setting in VSCode
- Manually validate and/or fix, by running Prettier locally using the following commands:
npm run prettier:check # Check for formatting issues
npm run prettier:fix # Fix formatting issues
The app uses ESLint with a plugin for TypeScript support. Note currently with NextJS v14
, this command won't run due to a dependency issue with ESLint v9
support. Hopefully resolved by NextJS soon.
npm run lint
Run Typescript's tsc
compiler for type-checking directly.
npm run ts-lint
Test fixtures can be accessed by pointing the app to a Test Environment API.
Note: Only currently supported in local dev environments. Tests are flaky due to network requests in Github Actions CI env.
NEXT_PUBLIC_DCAPI_ENDPOINT="https://dc-test-api.rdc-staging.library.northwestern.edu/api/v2"
# Start local server (automatically points NEXT_PUBLIC_DCAPI_ENDPOINT to the test data API)
npm run dev:playwright
# If in AWS Dev Environment, set a BASE_URL environment variable in a .env.local file
BASE_URL="[YOUR_DEV_ID].dev.rdc.library.northwestern.edu"
# Start Playwright tests in headless mode
npm run test:playwright
To run visual tests or debug errors, try experimenting with:
# Run in an interactive test browser to visually see tests run
npx playwright test --ui
# Run all tests in headed mode
npx playwright test --headed
For more info, view the docs: Playwright.
Unit tests use Jest and Testing Library React. Convention is to write tests alongside their respective components:
# Sample directory
/components/search/Search.tsx
/components/search/Search.test.tsx
...
To run Jest w/ React Testing-Library support, run:
npm run test
npm run analyze
will run the Next Bundle Analyzer to show snapshots of the app's bundled JS.
Manually sourced from Iconicons and locally created in components/Shared/SVG/Icons.tsx
, as opposed to including the entire NPM package direct.