- 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.
├── .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
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
The application can be run natively or in a Docker container.
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:
- Install dependencies
npm ci
- Optionally, disable telemetry data collection
npx next telemetry disable
- Run the local development server
npm run dev
- Navigate to localhost:3000 to view the application
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.
npm run build
- Builds the production Next.js bundlenpm start
- Runs the Next.js server, after building the production bundle
Alternatively, you can run the application in a Docker container.
From the /frontend
directory:
- Run the local development server
make dev
- 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 runmake 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.
To test the release target locally, run:
make release-build OPTS="--tag [IMAGE_NAME]"
ordocker 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 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.
From the frontend/
directory:
npm run storybook
- Navigate to localhost:6006 to view
npm run storybook-build
- Exports a static site tostorybook-static/
Alternatively, you can run Storybook in a Docker container.
From the frontend/
directory:
make storybook
- Navigate to localhost:6006 to view
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 reportnpm run test-update
- Updates test snapshotsnpm 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
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 testsnpm run test:e2e
— Runs all E2E tests using the playwright config found attests/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:
- Download the VS Code extension described in these Playwright docs
- 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.
- 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
-
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 atfrontend/.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 run ts:check
- Type checks all filesnpm run lint
- Lints all files and reports any errorsnpm run lint-fix
- Lints all files and fixes any auto-fixable errorsnpm run format
: Formats all files based on prettier rulesnpm run format-check
: Check files for prettier formatting violations without fixing themnpm 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
- 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 ofnpm run dev
).
- 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
- 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
- Internationalization
- Feature Flags
- Refer to the architecture decision records for more context on technical decisions.