DXP Scout

React app build for www.nypl.org. Pages and templates currently in repo:

• Homepage - https://www.nypl.org
• Section Fronts:
  • Books, Music, Movies - https://www.nypl.org/books-music-movies
  • Center for Education & Schools - https://www.nypl.org/education/educators
  • Education - https://www.nypl.org/education
  • Events - https://www.nypl.org/events
  • Give - https://www.nypl.org/give
  • Research - https://www.nypl.org/research
  • Support - https://www.nypl.org/research/support
  • Online Resources - https://www.nypl.org/research/collections/online-resources-databases
• Location Finder - https://www.nypl.org/locations
• Blog - https://www.nypl.org/blog
• Press Releases - https://www.nypl.org/press

Requirements

• NodeJS to install visit NodeJS (node: v22, npm: v11)
• NVM to install go to NVM github page
• Git to install go to Git Page
• Code Editor VSCode

Installation Scout (Local)

Follow these steps to setup a local installation of the project:

1. Clone the repo

git clone [email protected]:NYPL/dxp-react-search.git

Then open the folder

cd dxp-react-search

2. Install all the node dependencies

Check your node version and npm version first

node -v

v22.9.0

npm -v

11.5.2

If the output is not Node v22, either install it directly or use nvm.

# This will pick up v22 from the local `.nvmrc` file
nvm use

Finally, run the following to install all dependencies.

npm install

3. Copy .env.example to create a local .env file

cp .env.example .env

4. Update values in .env

example: NEXT_PUBLIC_GOOGLE_MAPS_API with the NYPL Google Maps/Geocode API Key

5. Start development server

npm run dev

6. Alternatively you start the production mode server

npm run build && npm start

Dev Tools

GraphQL

You can create and test GraphQL queries and see results without creating a front end by installing the Apollo Client Devtools extension (recommended) or by using the GraphQL tool at http://localhost:3000/api/graphql

Code Editor Setup

VS Code editor is the recommended IDE for React development. These are recommended VS Code extensions that will help with dev work.

• Prettier
• ESLint
• ES7 + React/Redux
• Auto Import
• DotENV
• GraphQL
• MDX
• Project Manager

App Testing

Unit tests

npm test

Playwright Tests (E2E)

Note about the CI environment variable:

The CI environment variable can be true, false, or undefined (evaluating as falsey).

When CI=true:

• Tests will fail if test.only is left in the code
• Will retry a test once if it fails the first time
• Only one test runs (no parallel workers)

When CI=false or undefined:

• Tests will NOT fail if test.only is left in the code
• Will NOT retry a test if it fails the first time
• Unlimited parallel workers

See Playwright documentation on CI for more details.

Playwright is used for end-to-end (E2E) testing to ensure that key user flows and pages work as expected in real browsers. These tests help catch issues that unit and integration tests might miss, and are run automatically in CI for every pull request to development, qa, and production branches.

Install Playwright Browsers

After installing dependencies (npm install or npm ci), install Playwright browsers with:

npx playwright install

You only need to run this once after first installing Playwright. This step installs the required browser binaries for Playwright tests.

Running Playwright Tests

How to run Playwright tests locally:

1. Start your development server:

npm run dev

2. In another terminal, run Playwright tests:

npx playwright test
# or
npm run pw

To run tests in headed mode (with browser UI):

npx playwright test --headed
# or
npm run pw:head

To run tests in headed mode with Playwright UI:

npm run pw:ui

3. To view the last HTML report:

npx playwright show-report

Skipping Tests in CI by Tag

Tests can be excluded from CI runs by adding a tag to the --grep-invert flag in .github/workflows/playwright.yml.

Tags are defined in the "Set excluded tags" step. The BASE variable holds tags that are skipped on all branches. To skip a tag only on a specific branch (e.g. production), add it to the matching condition.

Example — skip @events tests on production only:

1. Tag your test with @events:

test("should display event details @events", async () => { ... });

2. In the workflow, add it to the production condition:

if [ "$BRANCH_NAME" = "production" ]; then
echo "EXCLUDE_TAGS=$BASE|@events" >> $GITHUB_ENV

To skip a tag across all branches, add it to the BASE variable instead:

BASE="@images|@articlesdatabases|@locationhours|@regression|@events"

Bulk Redirect Tests for Articles & Databases

There are two types of redirect tests for Articles & Databases:

• Regular redirect tests:
  These test 5 key URLs and run automatically on every PR in CI.

• Bulk redirect tests:
  These test all URLs listed in the JSON file (articles-databases-redirects.json).
  Bulk tests are not run automatically in CI or on every PR.
  Developers should run them manually after major updates to redirects, before releases, or as needed.

How to run bulk redirect tests:

npm run pw:articlesdatabases

This will run the full suite of bulk redirect tests and report any failures. Update the documentation or JSON file as needed based on results.

Cypress Tests (E2E)

Running Tests

First, build the app and start it.

npm run build && npm start

Next, open another terminal window in the same directory.

To run all the tests in a headless state, via the CLI...

npm run cy:run

To run the tests via the Cypress GUI and view the results in the browser...

npm run cy:open

Deployment

We use Github ACtions for continuous integration and delivery. Builds are started on git push to a target branch per environment (development, qa, production). Deployment to AWS will occur on successful build to an Elastic Container Service cluster.

Next JS Asset Prefix

NYPL runs a reverse proxy in order to serve multiple different apps under the nypl.org domain.

For this app, the QA and PROD environment will use an ASSET_PREFIX .env variable that is wired up to the Next JS assetPrefix config.

This will prefix all Next JS assets for this app with /scout so the RP rules can route the correct assets to the correct app.

Other Next JS apps will use a different prefix.

For local development, ASSET_PREFIX should just be set to a blank string, like in the .env.example file.