Welcome to the Comet Starter App!

The goal of this project is to provide a React with TypeScript starter application, which comes pre-configured with the USWDS-based Comet Component Library as well as other tools to accelerate development. Some of these tools are as follows:

• Tooling: Vite
• Platform: React with TypeScript
• Component Library: Comet Component Library
• Data Visualization: Victory Charts
• Global State Management: Jotai
• Asynchronous State Management: Tanstack Query
• API Support: Axios
• Form Validation: TanStack Form with Zod
• Unit Testing: Vitest with React Testing Library
• Code Analysis: ESLint
• Code Formatting: Prettier
• End-to-End (E2E) Testing: Playwright
• Accessibility Testing: Unlighthouse
• API Testing: Jupyter Notebooks
• Authentication Support: Keycloak

Table of Contents

1. Running the Project Locally
2. Running with Docker
3. Running Unit Tests
4. Running Code Quality Checks
5. Running End-to-End (E2E) Tests
6. Running Accessibility (a11y) Tests
7. Contributing
8. Next Steps

Running the Project Locally

1. To install dependencies, run the following:

npm install

2. Install Recommended VS Code Extensions (optional)

3. To run locally with SSO, add a file called .env.local to the comet-starter directory. Copy and paste the template below and replace the placeholder values with your own (optional):

VITE_SSO_AUTHORITY=[SOME_KEYCLOAK_REALM_URL] # Ex: http://localhost:8088/realms/dev
VITE_SSO_CLIENT_ID=[SOME_CLIENT_ID] # Ex: dev-client

4. To start the app, run the following:

npm run dev

Running with Docker

1. To build the image, run the following:

docker build . -t comet-starter

2. To run the container, run the following:

docker run -p 8080:8080 --name comet-starter comet-starter

3. Access the app by navigating to: http://localhost:8080

Running Unit Tests

To make sure your changes do not break any unit tests, run the following:

npm run test

Ensure to review the coverage directory for code coverage details.

npm run test:coverage

Running Code Quality Checks

To make sure your changes adhere to additional code quality standards, run the following:

npm run lint
npm run format

You can also see the .vscode/settings.json file to find how to enable auto-formatting on save.

Running End-to-End (E2E) Tests

Note: running E2E tests requires a deployed or running app.

1. To run against a deployed app, add the following to your .env.local (optional):

VITE_BASE_URL=SOME_URL # Ex: 'https://metrostar.github.io/comet-starter/'

2. To install playwright dependencies, run the following (only required the first time):

npx playwright install

3. To run e2e tests, run the following:

npm run e2e

Running Accessibility (a11y) Tests

Note: running accessibility tests requires a deployed or running app.

1. To run against a deployed app, add the following to your .env.local (optional):

VITE_BASE_URL=SOME_URL # Ex: 'https://metrostar.github.io/comet-starter/'

2. To run accessibility tests, run the following:

npm run a11y

Contributing

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature_a)
3. Commit your Changes (git commit -m 'Added new feature_a')
4. Push to the Branch (git push origin feature_a)
5. Open a Pull Request

Next Steps

The following provides a short list of tasks which are potential next steps for this project. These could be steps in making use of this baseline or they could be for learning purposes.

• Apply/clean-up basic branding (title, header, footer, logo, favicon, etc)
• Add/Update Dashboard, About, Contact Us pages with applicable content
• Enhance Dashboard table functionality (filter, search, paging)
• Add Profile page and Profile Menu to Header (include Sign In/Sign Out, Profile, etc)
• Integrate with some API (Ex. Comet API)
• Integrate with some Identity Provider to support Single Sign-On (SSO)
• Deploy to cloud infrastructure