Front End from Nava next.js template (#283)

Co-authored-by: Daphne Gold <[email protected]>

.github/workflows/cd-storybook.yml

@@ -0,0 +1,60 @@
+name: Deploy Storybook
+
+on:
+  # Runs on pushes targeting the default branch
+  # !! Uncomment the lines below to enable this workflow
+  # push:
+  #   branches: ["main"]
+  #   paths:
+  #     - frontend/**
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow access to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Cancel any older in-progress runs of this workflow
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache-dependency-path: ./frontend/package-lock.json # or yarn.lock
+          cache: npm # or yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+        id: pages_config
+      - name: Install dependencies
+        run: npm ci
+        working-directory: ./frontend
+      - name: Build
+        run: NEXT_PUBLIC_BASE_PATH=${{ steps.pages_config.outputs.base_path }} npm run storybook-build
+        working-directory: ./frontend
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./frontend/storybook-static
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.hosting.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: hosting
+        uses: actions/deploy-pages@v1

.github/workflows/ci-frontend.yml

@@ -0,0 +1,123 @@
+name: CI - Front End
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - frontend/**
+      - .github/workflows/ci-frontend.yml
+
+defaults:
+  run:
+    working-directory: ./frontend
+
+env:
+  NODE_VERSION: 18
+  LOCKFILE_PATH: ./frontend/package-lock.json # or yarn.lock
+  PACKAGE_MANAGER: npm # or yarn
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache-dependency-path: ${{ env.LOCKFILE_PATH }}
+          cache: ${{ env.PACKAGE_MANAGER }}
+      - run: npm ci
+      - run: npm run test
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache-dependency-path: ${{ env.LOCKFILE_PATH }}
+          cache: ${{ env.PACKAGE_MANAGER }}
+      - run: npm ci
+      - run: npm run lint
+
+  types:
+    name: Type check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache-dependency-path: ${{ env.LOCKFILE_PATH }}
+          cache: ${{ env.PACKAGE_MANAGER }}
+      - run: npm ci
+      - run: npm run ts:check
+
+  formatting:
+    name: Format check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache-dependency-path: ${{ env.LOCKFILE_PATH }}
+          cache: ${{ env.PACKAGE_MANAGER }}
+      - run: npm ci
+      - run: npm run format-check
+
+  # Confirms the front end still builds successfully
+  check-frontend-builds:
+    name: Build check - Front End
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache-dependency-path: ${{ env.LOCKFILE_PATH }}
+          cache: ${{ env.PACKAGE_MANAGER }}
+
+      # https://nextjs.org/docs/advanced-features/ci-build-caching
+      - uses: actions/cache@v3
+        with:
+          path: |
+            ~/.npm
+            ${{ github.workspace }}/frontend/.next/cache
+          # Generate a new cache whenever packages or source files change.
+          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
+          # If source files changed but packages didn't, rebuild from a prior cache.
+          restore-keys: |
+            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
+
+      - run: npm ci
+      - run: npm run build -- --no-lint
+
+  # Confirms Storybook still builds successfully
+  check-storybook-builds:
+    name: Build check - Storybook
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache-dependency-path: ${{ env.LOCKFILE_PATH }}
+          cache: ${{ env.PACKAGE_MANAGER }}
+      - run: npm ci
+      - run: npm run storybook-build

.grype.yml

@@ -0,0 +1,18 @@
+# List of vulnerabilities to ignore for the anchore scan
+# https://github.com/anchore/grype#specifying-matches-to-ignore
+# More info can be found in the docs/infra/vulnerability-management.md file
+
+# Please add safelists in the following format to make it easier when checking
+# Package/module name: URL to vulnerability for checking updates
+#  Versions:     URL to the version history
+#  Dependencies: Name of any other packages or modules that are dependent on this version
+#                 Link to the dependencies for ease of checking for updates
+#  Issue:         Why there is a finding and why this is here or not been removed
+#  Last checked:  Date last checked in scans
+# - vulnerability: The-CVE-or-vuln-id # Remove comment at start of line
+
+ignore:
+  # These settings ignore any findings that fall into these categories
+  - fix-state: not-fixed
+  - fix-state: wont-fix
+  - fix-state: unknown

docker-compose.yml

@@ -29,7 +29,37 @@ services:
     depends_on:
       - main-db
 
-volumes:
-  dbdata:
+  nextjs:
+    container_name: next-dev
+    build:
+      context: ./frontend
+      target: dev
+    env_file:
+      # Add your non-secret environment variables to this file:
+      - ./frontend/.env.development
+      # If you have secrets, add them to this file and uncomment this line:
+      # - ./frontend/.env.local
+    volumes:
+      - ./frontend/src:/frontend/src
+      - ./frontend/public:/frontend/public
+    restart: always
+    ports:
+      - 3000:3000
 
+  storybook:
+    container_name: storybook
+    build:
+      context: ./frontend
+      target: dev
+    command: npm run storybook
+    volumes:
+      - ./frontend/src:/frontend/src
+      - ./frontend/public:/frontend/public
+      - ./frontend/.storybook:/frontend/.storybook
+      - ./frontend/stories:/frontend/stories
+    restart: always
+    ports:
+      - 6006:6006
 
+volumes:
+  dbdata:

documentation/decisions/adr/0015-fe-use-npm.md

@@ -0,0 +1,21 @@
+# Use NPM over Yarn Architectural Decision Records
+
+* Deciders: @aligg, @sawyerh, @lorenyu
+* Date: 2022-09
+
+
+## Context and Problem Statement
+Initially this template repo used yarn for package management. We moved to npm because:
+* npm is pre-bundled with node, so using npm removes an installation step
+* some projects work on government furnished equipment and an additional package installation (e.g. installing yarn) is a significant and time-consuming step
+* npm and yarn are comparable in function for the purposes of this template
+
+
+## Considered Options
+We considered the merits of yarn and npm only when making this decision.
+
+## Decision Outcome
+Chose npm to reduce installations and bureaucratic hurdles for folks using this template out of the box.
+
+## Links
+* [Original github issue for reference](https://github.com/navapbc/template-application-nextjs/issues/11)

documentation/decisions/adr/0016-fe-design-system.md

@@ -0,0 +1,40 @@
+# Use U.S. Web Design System for components and utility classes
+
+- Status: Accepted
+- Deciders: Loren Yu, Rocket Lee, Sawyer Hollenshead
+
+## Context and Problem Statement
+
+Projects should avoid reinventing the wheel where possible. A common place to do this is in the UI, by using a design system for frontend components and utility classes. This can help avoid inconsistencies in the UI, and can reduce barriers for new developers.
+
+We want to use a design system that is:
+
+- Section 508 compliant
+- Open source
+- Well maintained and documented
+- Includes the typical components and design patterns needed for government websites
+
+## Considered Options
+
+- [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/)
+- [CMS Design System](https://design.cms.gov/)
+
+## Decision Outcome
+
+The template will provide U.S. Web Design System styling out of the box.
+
+We will not follow their [install directions](https://designsystem.digital.gov/documentation/getting-started/developers), which suggests using Gulp as a task runner. Instead, to reduce the number of dependencies and configuration, we'll leverage Next.js's and Storybook's built-in Sass support. Copying the USWDS static assets into the project will be handled by a [`postinstall`](https://docs.npmjs.com/cli/v8/using-npm/scripts) script in `package.json`.
+
+### Positive Consequences
+
+- USWDS is the most popular design system for U.S. government websites and is maintained by GSA employees. It is the recommended way to meet the website standards detailed in the [21st Century Integrated Digital Experience Act](https://digital.gov/resources/21st-century-integrated-digital-experience-act/). [More key benefits can be read about here](https://designsystem.digital.gov/about/key-benefits/).
+- [Project teams can theme the USWDS](https://www.navapbc.com/insights/us-web-design-system) if their project needs to match an existing brand.
+
+### Negative Consequences
+
+- Unlike the CMS Design System, USWDS doesn't provide React components. Project teams will need to create their own React components that output USWDS markup, or install a third-party library like [`react-uswds`](https://github.com/trussworks/react-uswds). In the future, [the template could include this library by default](https://github.com/navapbc/template-application-nextjs/issues/19).
+- CMS projects may need to swap out USWDS for the CMS Design System, although the CMS Design System is based on USWDS, so this may not be necessary right away.
+
+## Links
+
+- [Previous research was done by Kalvin Wang and Shannon Alexander Navarro related to USWDS React libraries](https://docs.google.com/document/d/1KRWzH_wJUPKkFmBlxj6SM2yN3W7Or89Wa4TBVM3Ksog/edit)

documentation/decisions/adr/0017-fe-uswds-in-react.md

@@ -0,0 +1,73 @@
+# U.S. Web Design System in React
+
+- Status: Accepted
+- Deciders: @sawyerh, @aligg, @lorenyu, @rocketnova
+- Date: 2022-12-05
+
+Technical Story: #19
+
+## Context and Problem Statement
+
+- The U.S. Web Design System (USWDS) only provides HTML and CSS for its components. It includes a small bit of vanilla JS to add interactivity to some components like the date picker.
+- It's common for projects to write their own React components to output the USWDS HTML, to reduce the amount of boilerplate needed to use the USWDS components.
+- [Previous research by Kalvin and Shannon](https://docs.google.com/document/d/1KRWzH_wJUPKkFmBlxj6SM2yN3W7Or89Wa4TBVM3Ksog/edit) discovered that Nava engineers and designers universally agreed that being able to use a React USWDS component library when starting new projects would be valuable.
+
+## Considered Options
+
+- Use the existing open source [`react-uswds` library](https://github.com/trussworks/react-uswds)
+- Create our own React USWDS component library
+- Leave the responsibility to each project team
+
+## Decision Outcome
+
+Add [`react-uswds`](https://github.com/trussworks/react-uswds) as a template dependency, making it available to all teams who use the template. The primary reasons are to avoid reinventing the wheel and because it's overall a well-built and maintained library.
+
+## Pros and Cons of the Options
+
+### Use the existing open source [`react-uswds` library](https://github.com/trussworks/react-uswds)
+
+`react-uswds` is maintained by Truss, another vendor in this space. [A Storybook for it can be found here](https://trussworks.github.io/react-uswds/). Truss also maintains a [USWDS Figma library](https://www.figma.com/community/file/836611771720754351) for designers.
+
+#### Pros
+
+- Includes React components for all USWDS components and patterns.
+- Fairly well maintained.
+- Intentionally does not include any non-USWDS components.
+- Supports USWDS v3 (latest version)
+- This was the recommended approach coming out of [Kalvin and Shannon's research](https://docs.google.com/document/d/1KRWzH_wJUPKkFmBlxj6SM2yN3W7Or89Wa4TBVM3Ksog/edit).
+
+#### Cons
+
+- They [pin the `@uswds/uswds` dependency version](https://github.com/trussworks/react-uswds/blob/a0558b69ec5b99903cfa8edddf2d8b058f5e296c/package.json#L52) to a specific version, which means that a project cannot use a newer version of USWDS until `react-uswds` updates it on their end. In practice, this could mean that a project may have delayed access to new component styles or CSS bug fixes that USWDS releases.
+- Not necessarily a con, but just to call it out: We've only done a lightweight review of their technical implementation and hygiene — there's testing and linting, no reported a11y issues are open in GitHub or reported in Storybook, but we haven't done a comprehensive review of their code or a full accessibility audit. We're operating on trust in Truss's technical expertise, and an assumption that the outputted HTML markup is close to identical to what USWDS provides, so any a11y issues would likely be on USWDS's end.
+
+### Create our own React USWDS component library
+
+Nava could create our own React USWDS component library, similar to `react-uswds`.
+
+#### Pros
+
+- We'd have full control over the technical approach and wouldn't have a dependency on another vendor to incorporate changes or release new versions.
+
+#### Cons
+
+- Requires more time and effort than using an existing library. We'd have to build and maintain the library.
+- Reinventing the wheel. We can always fork `react-uswds` if it no longer meets our needs.
+
+### Leave the responsibility to each project team
+
+This is the current approach. Each project team is responsible for creating their own React components for the USWDS components they need.
+
+#### Pros
+
+- No additional work required from the Platform team.
+
+#### Cons
+
+- Each project team has to spend time and effort building the components or making technical decisions related to how they'll integrate USWDS. Teams then have to write their own tests and fix their own bugs for these components. Overall a potential poor use of time and effort.
+
+## Links
+
+- [Decision to use the USWDS](./0003-design-system.md)
+- [Kalvin and Shannon's research](https://docs.google.com/document/d/1KRWzH_wJUPKkFmBlxj6SM2yN3W7Or89Wa4TBVM3Ksog/edit)
+  - [Evaluation of `react-uswds`](https://docs.google.com/document/d/1T3eG4oRofDE_NkfL7-xEqS39ORlrXlI8bFYcjGaYoWs/edit)