frontend

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

💻 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.

Native

There are several secret environment variables necessary to submit the form related to email subscription. Duplicate the /frontend/env.development file and name the copy /frontend/.env.local, which will not be checked into github. Fill in the three variables related to Sendy. Ask another engineer on the team for those values if you don't have them.

From the frontend/ directory:

1. Install dependencies

   npm install

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

Other scripts

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

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, uncomment the correct environment variable for the API_URL in your .env.development 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

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

• TypeScript is used for type checking.
  • npm run ts:check - Type checks all files
• ESLint is used for linting. This helps catch common mistakes and encourage best practices.
  • npm run lint - Lints all files and reports any errors
  • npm run lint-fix - Lints all files and fixes any auto-fixable errors
• Prettier is used for code formatting. This reduces the need for manual formatting or nitpicking and enforces a consistent style.
  • npm run format: Formats all files
  • npm run format-check: Check files for formatting violations without fixing them.

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.

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

Testing the newsletter subscription form

The project uses Sendy to manage the newsletter. To the /subscribe form locally, Sendy test environment variables need to be added to the .env.local file or exported as environment variables:

SENDY_API_KEY=
SENDY_API_URL=
SENDY_LIST_ID=

These are stored as parameters in AWS System Manager and can be obtained there or from another developer on the team. They are not available for outside contributors.

Other topics

• Internationalization
• Feature Flags
• Refer to the architecture decision records for more context on technical decisions.