Note for DPLA Local: For DPLA Local instance configuration, refer to LOCAL.md.

DPLA Frontend

This is the repository for the Digital Public Library of America's new frontend.

Getting Started For Development

Install the Yarn package manager

Installation instructions

Check this project out from GitHub

$ git clone https://github.com/dpla/dpla-frontend.git

Install Node

We are using the "Fermium" version of Node.

The easiest way to manage your Node versions is with NVM. Follow the instructions on that page to set it up. Then, do the following in your shell:

$ cd /path/to/dpla-frontend  # Checked out above from GitHub
$ nvm install                # Picks up correct Node version from `.nvmrc`
$ nvm use                    # Activates correct Node version

Install Yarn

The recommended way to install Yarn:

npm install --global yarn

Install dependencies and start the local development server

$ yarn dev

You may now open http://localhost:3000/ in your browser.

Run with Docker

$ yarn build
$ yarn docker:build
$ yarn docker:run

See the Docker documentation and docker help for more information on using Docker containers. See package.json for more Docker-related commands.

Environmental Variables

The system makes extensive use of environment variables to decouple the different developing environments. It also uses a environment constants file for front-end runtime access of a subset of these variables. For local development it is best to use a .env file to provide these variables to the server. There is a .env.example you can work from. A constants/env.example.js is also provided; rename this file to constants/env.js and include the applicable values. Below is a list of the environment variables in use:

• API_KEY: your DPLA API key
• API_URL: the DPLA API base URL
• LOCAL_ID: ID of the Local partner (also exposed in constants/env.js)
• MUST_FORK: if "true", forces the server to fork and use multiple CPUs in development mode. This is only relevant when NODE_ENV is not equal to "production", e.g. when running yarn dev. The server always forks when NODE_ENV=production.
• NODE_ENV: the node environment, development or production
• SITE_ENV: the environment's type, user, pro, or local (also exposed in constants/env.js)
• BASE_URL: base URL for user site to allow for fully-rendered backlinks to point to the correct place (e.g. in citaitons)

Yarn / NPM Scripts

The project includes a number of scripts used for development, testing, and deployment. See package.json for details if you are a developer. They include:

• yarn run clean - Removes local Node modules, .next build targets, etc.
• yarn run dev - Builds the project and starts the server in development mode
• yarn run build - Builds the project for production
• yarn run start - Builds the project and starts the server in production mode

Cypress tests

Cypress will be installed along with the other dev dependencies.

The tests require fixtures, some of which are auto-generated by a script. Run this command to write out the automated fixtures:

yarn run cy:fixtures

Once those are in place, you can run all the tests with:

yarn run cy:run

Or open the test IDE to run them individually with:

yarn run cy:open

To record the tests to the Cypress cloud, you need to set the environmental variable CYPRESS_RECORD_KEY to the UUID generated for the project. This UUID is available in the Cypress Cloud interface for this project if you are logged in. Once that is set, record the test suite to the Cypress Cloud dashboard with:

yarn run cy:record

Other than recording tests, the CYPRESS_RECORD_KEY is not necessary.