Skip to content

Commit ddc9b87

Browse files
yoomlamyoomlam
authored
feat: Add NextJS frontend template (#20)
1 parent 8876499 commit ddc9b87

68 files changed

Lines changed: 21664 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/cd-frontend-storybook.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Deploy Storybook
2+
3+
on:
4+
# !! When you are ready to enable Storybook CD, run:
5+
#
6+
# nava-platform app update --data app_enable_storybook_cd=true . <APP_NAME>
7+
#
8+
# to enable these lines. They are here as comments for context.
9+
#
10+
# push:
11+
# branches: ["main"]
12+
# paths:
13+
# - frontend/**
14+
15+
# Allows you to run this workflow manually from the Actions tab
16+
workflow_dispatch:
17+
18+
# Sets permissions of the GITHUB_TOKEN to allow access to GitHub Pages
19+
permissions:
20+
contents: read
21+
pages: write
22+
id-token: write
23+
24+
# Cancel any older in-progress runs of this workflow
25+
concurrency:
26+
group: "pages"
27+
cancel-in-progress: true
28+
29+
jobs:
30+
build:
31+
runs-on: ubuntu-latest
32+
steps:
33+
- name: Checkout
34+
uses: actions/checkout@v4
35+
- name: Setup Node
36+
uses: actions/setup-node@v4
37+
with:
38+
node-version: 20
39+
cache-dependency-path: ./frontend/package-lock.json # or yarn.lock
40+
cache: npm # or yarn
41+
- name: Setup Pages
42+
uses: actions/configure-pages@v5
43+
id: pages_config
44+
- name: Install dependencies
45+
run: npm ci
46+
working-directory: ./frontend
47+
- name: Build
48+
run: NEXT_PUBLIC_BASE_PATH=${{ steps.pages_config.outputs.base_path }} npm run storybook-build
49+
working-directory: ./frontend
50+
- name: Upload artifact
51+
uses: actions/upload-pages-artifact@v3
52+
with:
53+
path: ./frontend/storybook-static
54+
55+
deploy:
56+
environment:
57+
name: github-pages
58+
url: ${{ steps.hosting.outputs.page_url }}
59+
runs-on: ubuntu-latest
60+
needs: build
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: hosting
64+
uses: actions/deploy-pages@v4

‎.github/workflows/ci-frontend.yml‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
name: CI - frontend
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
paths:
9+
- frontend/**
10+
- .github/workflows/ci-frontend.yml
11+
12+
defaults:
13+
run:
14+
working-directory: ./frontend
15+
16+
env:
17+
NODE_VERSION: 20
18+
LOCKFILE_PATH: ./frontend/package-lock.json # or yarn.lock
19+
PACKAGE_MANAGER: npm # or yarn
20+
21+
concurrency:
22+
group: ${{ github.workflow }}-${{ github.ref }}
23+
cancel-in-progress: true
24+
25+
jobs:
26+
tests:
27+
name: Tests
28+
runs-on: ubuntu-latest
29+
30+
steps:
31+
- uses: actions/checkout@v4
32+
- uses: actions/setup-node@v4
33+
with:
34+
node-version: ${{ env.NODE_VERSION }}
35+
cache-dependency-path: ${{ env.LOCKFILE_PATH }}
36+
cache: ${{ env.PACKAGE_MANAGER }}
37+
- run: npm ci
38+
- run: npm run test -- --testLocationInResults --json --outputFile=coverage/report.json
39+
- uses: ArtiomTr/jest-coverage-report-action@v2
40+
with:
41+
coverage-file: coverage/report.json
42+
test-script: npm test
43+
working-directory: frontend
44+
annotations: failed-tests
45+
# base-coverage-file: report.json
46+
47+
lint:
48+
name: Lint
49+
runs-on: ubuntu-latest
50+
51+
steps:
52+
- uses: actions/checkout@v4
53+
- uses: actions/setup-node@v4
54+
with:
55+
node-version: ${{ env.NODE_VERSION }}
56+
cache-dependency-path: ${{ env.LOCKFILE_PATH }}
57+
cache: ${{ env.PACKAGE_MANAGER }}
58+
- run: npm ci
59+
- run: npm run lint
60+
61+
types:
62+
name: Type check
63+
runs-on: ubuntu-latest
64+
65+
steps:
66+
- uses: actions/checkout@v4
67+
- uses: actions/setup-node@v4
68+
with:
69+
node-version: ${{ env.NODE_VERSION }}
70+
cache-dependency-path: ${{ env.LOCKFILE_PATH }}
71+
cache: ${{ env.PACKAGE_MANAGER }}
72+
- run: npm ci
73+
- run: npm run ts:check
74+
75+
formatting:
76+
name: Format check
77+
runs-on: ubuntu-latest
78+
79+
steps:
80+
- uses: actions/checkout@v4
81+
- uses: actions/setup-node@v4
82+
with:
83+
node-version: ${{ env.NODE_VERSION }}
84+
cache-dependency-path: ${{ env.LOCKFILE_PATH }}
85+
cache: ${{ env.PACKAGE_MANAGER }}
86+
- run: npm ci
87+
- run: npm run format-check
88+
89+
# Confirms the app still builds successfully
90+
check-app-builds:
91+
name: Build check - App
92+
runs-on: ubuntu-latest
93+
94+
steps:
95+
- uses: actions/checkout@v4
96+
- uses: actions/setup-node@v4
97+
with:
98+
node-version: ${{ env.NODE_VERSION }}
99+
cache-dependency-path: ${{ env.LOCKFILE_PATH }}
100+
cache: ${{ env.PACKAGE_MANAGER }}
101+
102+
# https://nextjs.org/docs/advanced-features/ci-build-caching
103+
- uses: actions/cache@v4
104+
with:
105+
path: |
106+
~/.npm
107+
${{ github.workspace }}/frontend/.next/cache
108+
# Generate a new cache whenever packages or source files change.
109+
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
110+
# If source files changed but packages didn't, rebuild from a prior cache.
111+
restore-keys: |
112+
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
113+
114+
- run: npm ci
115+
- run: npm run build -- --no-lint
116+
117+
# Confirms Storybook still builds successfully
118+
check-storybook-builds:
119+
name: Build check - Storybook
120+
runs-on: ubuntu-latest
121+
122+
steps:
123+
- uses: actions/checkout@v4
124+
- uses: actions/setup-node@v4
125+
with:
126+
node-version: ${{ env.NODE_VERSION }}
127+
cache-dependency-path: ${{ env.LOCKFILE_PATH }}
128+
cache: ${{ env.PACKAGE_MANAGER }}
129+
- run: npm ci
130+
- run: npm run storybook-build

‎.github/workflows/markdownlint-config.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,24 @@
1111
},
1212
{
1313
"pattern": "https://navalabs.atlassian.net/browse/DST-"
14+
},
15+
{
16+
"pattern": "https://www.terraform.io"
17+
},
18+
{
19+
"pattern": "https://developer.hashicorp.com/"
20+
},
21+
{
22+
"pattern": "https://www.figma.com/community/file/"
23+
},
24+
{
25+
"pattern": "https://nextjs.org/docs/"
26+
},
27+
{
28+
"pattern": "https://remix.run/docs/"
29+
},
30+
{
31+
"pattern": "https://18f.gsa.gov/"
1432
}
1533
],
1634
"replacementPatterns": [

‎.template-application-nextjs/frontend.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Changes here will be overwritten by Copier
2+
_commit: v0.1.0
3+
_src_path: https://github.com/navapbc/template-application-nextjs
4+
app_enable_storybook_cd: false
5+
app_local_port: 3001
6+
app_name: frontend

‎docs/decisions/frontend/0000-use-markdown-architectural-decision-records.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Use Markdown Architectural Decision Records
2+
3+
## Context and Problem Statement
4+
5+
We want to record architectural decisions made in this project.
6+
Which format and structure should these records follow?
7+
8+
## Considered Options
9+
10+
* [MADR](https://adr.github.io/madr/) 2.1.2 – The Markdown Architectural Decision Records
11+
* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
12+
* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
13+
* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
14+
* Formless – No conventions for file format and structure
15+
16+
## Decision Outcome
17+
18+
Chosen option: "MADR 2.1.2", because
19+
20+
* Implicit assumptions should be made explicit.
21+
Design documentation is important to enable people to understand the decisions later on.
22+
See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
23+
* The MADR format is lean and fits our development style.
24+
* The MADR structure is comprehensible and facilitates usage & maintenance.
25+
* The MADR project is vivid.
26+
* Version 2.1.2 is the latest one available when starting to document ADRs.

‎docs/decisions/frontend/0001-use-npm.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Use NPM over Yarn Architectural Decision Records
2+
3+
* Deciders: @aligg, @sawyerh, @lorenyu
4+
* Date: 2022-09
5+
6+
7+
## Context and Problem Statement
8+
Initially, this template repo used yarn for package management. We moved to npm because:
9+
* npm is pre-bundled with node, so using npm removes an installation step
10+
* some projects work on government-furnished equipment and an additional package installation (e.g. installing yarn) is a significant and time-consuming step
11+
* npm and yarn are comparable in function for the purposes of this template
12+
13+
14+
## Considered Options
15+
We considered the merits of yarn and npm only when making this decision.
16+
17+
## Decision Outcome
18+
Chose npm to reduce installations and bureaucratic hurdles for folks using this template out of the box.
19+
20+
## Links
21+
* [Original GitHub issue for reference](https://github.com/navapbc/template-application-nextjs/issues/11)

‎docs/decisions/frontend/0003-design-system.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Use U.S. Web Design System for components and utility classes
2+
3+
- Status: Accepted
4+
- Deciders: Loren Yu, Rocket Lee, Sawyer Hollenshead
5+
6+
## Context and Problem Statement
7+
8+
Projects should avoid reinventing the wheel where possible. A common place to do this is in the UI, by using a design system for front-end components and utility classes. This can help avoid inconsistencies in the UI, and can reduce barriers for new developers.
9+
10+
We want to use a design system that is:
11+
12+
- Section 508 compliant
13+
- Open source
14+
- Well maintained and documented
15+
- Includes the typical components and design patterns needed for government websites
16+
17+
## Considered Options
18+
19+
- [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/)
20+
- [CMS Design System](https://design.cms.gov/)
21+
22+
## Decision Outcome
23+
24+
The template will provide U.S. Web Design System styling out of the box.
25+
26+
We will not follow their [install documentation](https://designsystem.digital.gov/documentation/getting-started-for-developers/), which suggests using Gulp as a task runner. Instead, to reduce the number of dependencies and configurations, 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`.
27+
28+
### Positive Consequences
29+
30+
- 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/).
31+
- [Project teams can theme the USWDS](https://www.navapbc.com/insights/us-web-design-system) if their project needs to match an existing brand.
32+
33+
### Negative Consequences
34+
35+
- 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).
36+
- 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.
37+
38+
## Links
39+
40+
- [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)

‎docs/decisions/frontend/0004-uswds-in-react.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# U.S. Web Design System in React
2+
3+
- Status: Accepted
4+
- Deciders: @sawyerh, @aligg, @lorenyu, @rocketnova
5+
- Date: 2022-12-05
6+
7+
Technical Story: #19
8+
9+
## Context and Problem Statement
10+
11+
- 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.
12+
- 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.
13+
- [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.
14+
15+
## Considered Options
16+
17+
- Use the existing open-source [`react-uswds` library](https://github.com/trussworks/react-uswds)
18+
- Create our own React USWDS component library
19+
- Leave the responsibility to each project team
20+
21+
## Decision Outcome
22+
23+
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.
24+
25+
## Pros and Cons of the Options
26+
27+
### Use the existing open-source [`react-uswds` library](https://github.com/trussworks/react-uswds)
28+
29+
`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.
30+
31+
#### Pros
32+
33+
- Includes React components for all USWDS components and patterns.
34+
- Fairly well maintained.
35+
- Intentionally does not include any non-USWDS components.
36+
- Supports USWDS v3 (latest version)
37+
- This was the recommended approach coming out of [Kalvin and Shannon's research](https://docs.google.com/document/d/1KRWzH_wJUPKkFmBlxj6SM2yN3W7Or89Wa4TBVM3Ksog/edit).
38+
39+
#### Cons
40+
41+
- 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.
42+
- 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.
43+
44+
### Create our own React USWDS component library
45+
46+
Nava could create our own React USWDS component library, similar to `react-uswds`.
47+
48+
#### Pros
49+
50+
- 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.
51+
52+
#### Cons
53+
54+
- Requires more time and effort than using an existing library. We'd have to build and maintain the library.
55+
- Reinventing the wheel. We can always fork `react-uswds` if it no longer meets our needs.
56+
57+
### Leave the responsibility to each project team
58+
59+
This is the current approach. Each project team is responsible for creating its own React components for the USWDS components they need.
60+
61+
#### Pros
62+
63+
- No additional work is required from the Platform team.
64+
65+
#### Cons
66+
67+
- 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 potentially poor use of time and effort.
68+
69+
## Links
70+
71+
- [Decision to use the USWDS](./0003-design-system.md)
72+
- [Kalvin and Shannon's research](https://docs.google.com/document/d/1KRWzH_wJUPKkFmBlxj6SM2yN3W7Or89Wa4TBVM3Ksog/edit)
73+
- [Evaluation of `react-uswds`](https://docs.google.com/document/d/1T3eG4oRofDE_NkfL7-xEqS39ORlrXlI8bFYcjGaYoWs/edit)

0 commit comments

Comments
 (0)