Frontend

Language

We use React as our frontend library. We do not use Angular, Vue, etc. There may sometimes be a reason to use pure vanilla JS and not use a frontend framework at all; that’s fine. In general, talk to the team and engineering directors before making a choice besides React.
TypeScript should be used over plain JavaScript. Static typing can be philosophically considered a form of testing: it provides immediate, useful feedback as to whether the code written satisfies the defined constraints.

React frameworks

Use Vite when building a Single-Page Application (SPA), using create-vite-app
Use Next.js when you need a full-stack framework and/or server-side components
Use Astro for content-centric static pages.

Talk to the team and engineering directors before making a choice besides these three frameworks.

Forms

We use React Hook Form (RHF) for handling form logic.

For user input validation, either use:

RHF’s native validation capabilities
Or use @hookform/resolvers to wire up Zod

Additionally, @hookform/lens may be useful for typesafe mapping of nested data to RHF.

See Design system (Grove) - Usage for examples of wrapping Grove components with RHF.

Some existing projects may still handle form logic and validation in different ways.

Testing

Unit tests

Use React Testing Library and vitest for frontend unit testing.

Install the following:

@testing-library/dom
@testing-library/jest-dom
@testing-library/react
@testing-library/user-event
jest-environment-jsdom

End-to-end tests

Use Playwright for end-to-end testing on new projects. Visit the ProfileNJ e2e testing decision doc for details on the justification.

However, many older projects still use Cypress.

If using Cypress, add an upload-artifact step, so that you can view screenshots if the CI fails in ways that you can’t reproduce

- name: Upload screenshots
  uses: actions/upload-artifact@v6
  if: failure()
  with:
    name: cypress-screenshots
    path: cypress/screenshots

Accessibility testing

For a11y testing, consider setting up Axe for Playwright.

In the project Readme include how to run tests, and how to run one specific test in one specific file. This is technically part of test framework doc, but has been TIL for multiple people.

Additional pages

We have dedicated page for guidance on the following components of frontend development: