app

Technical overview

This is a Next.js React web application, written in TypeScript. Storybook is included as a frontend workshop. A few related factors that influenced the selection of these tools are: the demo is frontend-only, while also needing the ability to dynamically render different claim scenarios in a user-friendly way.

U.S. Web Design System provides themeable styling and a set of common components.

Adopting this prototype

This prototype is intended to be a starting point. It is not intended to be a production-ready application. You should adopt this prototype by copying the files into your own project, and then modifying them to suit your needs.

Some suggested steps when adopting this prototype:

• Replace the prototype's mock API with your own API implementation and data model. The mock API request logic is in useClaimData.ts, and the response's type declarations are in types.ts.
• Copy the design patterns, either as React components or as their HTML markup. The prototype's status page is broken down into self-contained UI elements in the components/ directory. If a team isn't using React, they can rewrite the relevant pieces in their preferred templating language. Teams can reference how the U.S. Web Design System patterns are utilized, and copy the HTML markup into their own codebase.

📂 Directory structure

├── public            # Static assets (fonts, images, etc.)
│   ├── locales       # Internationalized content
│   └── mock-api      # Fake API responses for demos
├── src               # JS source code
│   ├── components    # Reusable UI components
│   └── pages         # Page routes and data fetching
│       ├── _app.tsx  # Wraps each pages
│       └── index.tsx # Claim status page
├── stories           # Storybook pages
├── styles            # Sass & design system settings
└── tests             # Unit & integration tests

💻 Development

Next.js provides the React framework for building the web application. Pages are defined in the pages/ directory. Pages are automatically routed based on the file name. For example, pages/index.tsx is the "home" page.

Learn more about developing Next.js applications ↗️

Getting started

Node.js (v14 or later) or Docker are required in order to run the application locally.

From the app/ 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
5. Toggle the demo scenario by setting the scenario query parameter in the URL to one of the file numbers in the mock-api/ directory. For example, http://localhost:3000?scenario=3.

Alternatively, you can run the application in a Docker container:

1. From the root directory run docker-compose up -d --build

Other scripts:

• npm run build - Builds the production bundle
• npm start - Runs the app in production mode

🖼️ 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.

From the app/ directory:

1. npm run storybook
2. Navigate to localhost:6006 to view
3. Toggle the demo scenario in the Storybook controls panel

Alternatively, you can run Storybook in a Docker container:

1. From the root directory run docker-compose exec nextjs npm run storybook

Other scripts:

• npm run storybook-build - Exports a static site to storybook-static/

🐛 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

🤖 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 file:

   {
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": true
     },
     "editor.formatOnSave": true,
     "editor.defaultFormatter": "esbenp.prettier-vscode",
     "eslint.workingDirectories": ["./app"],
     "typescript.validate.enable": true
   }

Other topics

• Accessibility
• Internationalization