Skip to content

Latest commit

 

History

History

frontend

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Overview

  • This is a Next.js React web application, written in TypeScript.
  • U.S. Web Design System provides themeable styling and a set of common components.
  • React-USWDS provides React components already with USWDS theming out of the box. For a reference point starting out, see react-uswds-hello.tsx which includes examples of react-uswds component usage.
  • Storybook is included as a frontend workshop.

Directory structure

├── .storybook        # Storybook configuration
├── public            # Static assets
│   └── locales       # Internationalized content
├── src               # Source code
│   ├── components    # Reusable UI components
│   ├── app           # Page routes and data fetching
│   │   └── api       # API routes (optional)
│   └── styles        # Sass & design system settings
├── stories           # Storybook pages
└── tests             # Unit and E2E tests

💻 Development

Next.js provides the React framework for building the web application. Pages are defined in the app/ directory. Pages are automatically routed based on the file name. For example, pages/[locale]/page.tsx is the home page.

Learn more about developing Next.js applications ↗️

Getting started

The application can be run natively or in a Docker container.

Running the app locally

Before running the server, duplicate the /frontend/env.development file and name the copy /frontend/.env.local, in order to avoid checking in any sensitive data to Github.

From the /frontend directory:

  1. Install dependencies
    npm ci
  2. Optionally, disable telemetry data collection
    npx next telemetry disable
  3. Run the local development server
    npm run dev
  4. Navigate to localhost:3000 to view the application

Secrets

Some functionality will not work locally without supplying the application environment variables containing secrets.

  • New Relic
    • NEW_RELIC_APP_NAME
    • NEW_RELIC_LICENSE_KEY
  • Email subscription form (Sendy)
    • SENDY_API_KEY
    • SENDY_API_URL
    • SENDY_LIST_ID

If you need to access this functionality locally, contact an engineer on the team to get access to the necessary secrets.

Other scripts

  • npm run build - Builds the production Next.js bundle
  • npm start - Runs the Next.js server, after building the production bundle

Running the app in Docker

Alternatively, you can run the application in a Docker container.

From the /frontend directory:

  1. Run the local development server
    make dev
  2. Navigate to localhost:3000 to view the application
  • If installing new packages locally with npm and using make dev with docker to run locally, you may need to run make build first to bring the new packages into the container

Note: To run the fully integrated app, with the Next JS app connecting to the API, uncomment the correct environment variable for the API_URL in your .env.development or .env.local file, and run make start in the API directory before starting your local frontend container.

Testing Release Target Locally

To test the release target locally, run:

  • make release-build OPTS="--tag [IMAGE_NAME]" or
  • docker buildx build --target release --tag [IMAGE_NAME] for a faster build on OSX

to build a local image. To view the site at localhost:3000, run: docker run -e "HOSTNAME=0.0.0.0" -p 3000:3000 [IMAGE_NAME].

🖼️ Storybook

Storybook is a frontend workshop for developing and documenting pages and components in isolation. It allows you to render the same React components and files in the src/ directory in a browser, without the need for a server or database. This allows you to develop and manually test components without having to run the entire Next.js application.

See the Storybook Next.js documentation for more information about using Storybook with Next.js

Similar to the Next.js application, Storybook can be ran natively or in a Docker container.

Native

From the frontend/ directory:

  1. npm run storybook
  2. Navigate to localhost:6006 to view

Other scripts

  • npm run storybook-build - Exports a static site to storybook-static/

Docker

Alternatively, you can run Storybook in a Docker container.

From the frontend/ directory:

  1. make storybook
  2. Navigate to localhost:6006 to view

Testing

🐛 Unit Testing

Jest is used as the test runner and React Testing Library provides React testing utilities.

Tests are manged as .test.ts (or .tsx) files in the the tests/ directory.

To run tests:

  • npm test - Runs all tests and outputs test coverage report
  • npm run test-update - Updates test snapshots
  • npm run test-watch - Runs tests in watch mode. Tests will re-run when files are changed, and an interactive prompt will allow you to run specific tests or update snapshots.

A subset of tests can be ran by passing a pattern to the script. For example, to only run tests in tests/pages/:

npm run test-watch -- pages

🚦 End-to-end (E2E) testing

Playwright is a framework for web testing and its test runner is called Playwright Test, which can be used to run E2E or integration tests across chromium, firefox, and webkit browsers.

E2E test filenames end with .spec.ts and are found in the tests/e2e directory.

To run E2E tests via CLI:

  • cd ../api && make init db-seed-local start (prerequisite to start the API)
  • npx playwright install --with-deps — Downloads playwright browsers required to run tests
  • npm run test:e2e — Runs all E2E tests using the playwright config found at tests/playwright.config.ts
  • npm run test:e2e:ui — Run specific or all E2E tests using Playwright's UI mode, which is useful for debugging full traces of each test

To run E2E tests using VS Code:

  1. Download the VS Code extension described in these Playwright docs
  2. Follow the instructions Playwright provides

Playwright E2E tests run "local-to-local", requiring both the frontend and the API to be running for the tests to pass - and for the database to be seeded with data.

In CI, the "Front-end Checks" workflow (.github/workflows/ci-frontend-e2e.yml) summary will include an "Artifacts" section where there is an attached "playwright-report". Playwright docs describe how to view HTML Report in more detail.

🤖 Type checking, linting, and formatting

Tools

  • TypeScript is used for type checking.
  • ESLint is used for linting. This helps catch common mistakes and encourage best practices.
  • Prettier is used for code formatting. This reduces the need for manual formatting or nitpicking and enforces a consistent style.PRs in Github Actions, other than e2e tests

It's recommended that developers configure their code editor to auto run these tools on file save. Most code editors have plugins for these tools or provide native support.

VSCode instructions
  1. Install the Prettier and ESLint extensions.

  2. Add the following to a .vscode/settings.json Workspace Settings file:

    {
      "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
      },
      "editor.formatOnSave": true,
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "eslint.workingDirectories": ["./frontend"],
      "typescript.validate.enable": true
    }

    For these tools to auto run, the settings must be located in the root of your current VSCode workspace. For example, if you open the frontend/ directory in VSCode, the settings should be located at frontend/.vscode/settings.json. If you then open then root repository directory in VSCode as your workspace, these tools will not auto run. (Note that adding the settings to the root repository directory may affect other parts of a monorepo.)

    You can alternatively add the settings to your User Settings, however they will apply globally to any workspace you open. See User and Workspace Settings for more guidance.

NPM Scripts for type checking, linting, and formatting

  • npm run ts:check - Type checks all files
  • npm run lint - Lints all files and reports any errors
  • npm run lint-fix - Lints all files and fixes any auto-fixable errors
  • npm run format: Formats all files based on prettier rules
  • npm run format-check: Check files for prettier formatting violations without fixing them
  • npm run all-checks: Runs linting, typescript check, unit testing, and creates a build - simulating locally tests that are run on PRs in Github Actions, other than e2e tests

Debugging the Next App in VSCode

  • See the debug config: ./.vscode/launch.json
    • There are several debug config targets defined there depending on if you want to debug just client components (client-side), just server components (server-side), or both (with the Full Stack option). You can also debug the built server (launched from npm start instead of npm run dev).
  • Run one of these launch targets from the VSCode debug menu
  • Place breakpoints in VSCode
  • Visit the relevant routes in the browser and confirm you can hit these breakpoints

Note that debugging the server-side or full-stack here doesn't debug the API. See the API readme for more information

Other topics