From 082e0386c4f9ace4c25dee00ecc142f4ef694eb5 Mon Sep 17 00:00:00 2001 From: acouch Date: Fri, 10 Jan 2025 16:29:13 -0500 Subject: [PATCH 1/6] Update dev docs for auth setup --- documentation/api/development.md | 131 +++++++++++++---------- documentation/frontend/authentication.md | 0 documentation/frontend/development.md | 86 +++++++++++++++ frontend/src/services/auth/README.md | 54 ---------- 4 files changed, 159 insertions(+), 112 deletions(-) create mode 100644 documentation/frontend/authentication.md create mode 100644 documentation/frontend/development.md delete mode 100644 frontend/src/services/auth/README.md diff --git a/documentation/api/development.md b/documentation/api/development.md index bb0e0e2e3..8fe2c4228 100644 --- a/documentation/api/development.md +++ b/documentation/api/development.md @@ -4,75 +4,40 @@ This application is dockerized. Take a look at [Dockerfile](../../api/Dockerfile A very simple [docker-compose.yml](../../docker-compose.yml) has been included to support local development and deployment. -## Prerequisites +Several components like tests, linting, and scripts can be run either inside of the Docker container, or outside on your machine. -1. Install the version of Python specified in [pyproject.toml](../../api/pyproject.toml) - [pyenv](https://github.com/pyenv/pyenv#installation) is one popular option for installing Python, - or [asdf](https://asdf-vm.com/). - - If using pyenv run `pyenv local ` to ensure that version will be used in subsequent steps -2. Ensure that `python -V` and `python3 -V` are picking up that version. - - If not, run `pyenv init -` and/or restart your shell to ensure it was run automatically -3. After installing and activating the right version of Python, install - [poetry](https://python-poetry.org/docs/#installation) and follow the instructions to add poetry to your path if necessary. - - ```bash - curl -sSL https://install.python-poetry.org | python3 - - ``` - -4. You'll also need [Docker Desktop](https://www.docker.com/products/docker-desktop/) +**Running in Docker is the default**, but on some machines like the M1 Mac, running natively may be desirable for performance reasons. -## **Note:** All the following commands should be run from the `/api` directory. +## Docker -## Database setup: Run Migrations/Seeds +This section covers development using Docker. There are a number of Docker commands included in the [Makefile](../../api/Makefile) which are helpful for local development. Run `make help` for a list of commands. -1. If you haven't done local development before you'll need to execute the migrations and seed the DB with data using the steps in [database-local-usage.md](database/database-local-usage.md) +### Setup -## OpenSearch setup +Run `make init && make run logs` to start the local containers. The application will be available at `http://localhost:8080/docs`. -1. Run `make init-opensearch` setup the OpenSearch Container -2. Run `make populate-search-opportunities` to push data previously seeded in the DB into the search index +This stands up the following services: -If your DB or OpenSearch end up in an odd place, you can reset all the persistent storage using `make volume-recreate` +* Flask API (http://localhost:8080) +* Postgres database +* OpenSearch node +* OpenSearchdashboard (http://localhost:5601) +* localstack +* mock oauth server (http://localhost:5001) -## Run the application +### Seed data -1. Make sure you have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed & running. -2. Run `make setup-local` to install dependencies -3. Run `make init start` to build the image and start the container. -4. Navigate to `localhost:8080/docs` to access the Swagger UI. -5. Run `make run-logs` to see the logs of the running API container -6. Run `make stop` when you are done to delete the container. +Run `make db-seed-local && populate-search-opportunities` to create local data in the database and make it available in the API. -## Some Useful Commands +### API Authenticaion -`make test` will run all of the tests. Additional arguments can be passed to this command which will be passed to pytest like so: `make test args="tests/api/route -v"` which would run all tests in the route folder with verbosity increased. See the [Pytest Docs](https://docs.pytest.org/en/7.1.x/reference/reference.html#command-line-flags) for more details on CLI flags you can set. - -`make clean-volumes` will spin down the docker containers + delete the volumes. - -`make volume-recreate` Deletes the volumes and then re-initializes the persistant portions of the stack. This can be useful to reset your DB, or fix any bad states your local environment may have gotten into. - -See the [Makefile](../../api/Makefile) for a full list of commands you can run. - -The `make console` command initializes a Python REPL environment pre-configured with database connectivity. This allows developers to perform database queries, utilize factories for data generation, and interact with the application's models directly. - -- Writing a query: `dbs.query(Opportunity).all()` -- Saving some factory generated data to the db: `f.OpportunityFactory.create()` - -## Docker and Native Development - -Several components like tests, linting, and scripts can be run either inside of the Docker container, or outside on your native machine. -Running in Docker is the default, but on some machines like the M1 Mac, running natively may be desirable for performance reasons. - -You can switch which way many of these components are run by setting the `PY_RUN_APPROACH` env variable in your terminal. - -- `export PY_RUN_APPROACH=local` will run these components natively -- `export PY_RUN_APPROACH=docker` will run these within Docker +This API uses a very simple [ApiKey authentication approach](https://apiflask.com/authentication/#use-external-authentication-library) which requires the caller to provide a static key. This is specified with the `API_AUTH_TOKEN` environment variable. -Note that even with the native mode, many components like the DB and API will only ever run in Docker, and you should always make sure that any implementations work within docker. +### User Authentication -Running in the native/local approach may require additional packages to be installed on your machine to get working. +Run `make setup-env-override-file` to create the `override.env` file which will include the necessary JWT keys for running the user. -## Environment Variables +### Environment Variables Most configuration options are managed by environment variables. @@ -80,11 +45,15 @@ Environment variables for local development are stored in the [local.env](../../ Any environment variables specified directly in the [docker-compose](../../docker-compose.yml) file will take precedent over those specified in the [local.env](../../api/local.env) file. -## Authentication +### Troubleshooting -This API uses a very simple [ApiKey authentication approach](https://apiflask.com/authentication/#use-external-authentication-library) which requires the caller to provide a static key. This is specified with the `API_AUTH_TOKEN` environment variable. +Errors in standing up the API can originate from an out of date container, database syncronization, or other issues with previously created services. Helper functions are available to rebuild: + +* **db-check-migrations** - check if migrations are out of sync +* **volume-recreate** - delete all existing volumes and data +* **remake-backend** - delete all data (`volume-recreate`) and load data (`db-seed-local` and `populate-search-opportunities`) -## VSCode Remote Attach Container Debugging +### VSCode Remote Attach Container Debugging The API can be run in debug mode that allows for remote attach debugging (currently only supported from VSCode) to the container. @@ -105,6 +74,52 @@ The API can be run in debug mode that allows for remote attach debugging (curren - You should now be able to hit set breakpoints throughout the API +## Local (non-Docker) + +Run `export PY_RUN_APPROACH=local` to run API and test functions locally when running commands in the Makefile. For example, `make test` or `make format` will run outside of Docker. + +**Note:** even with the native mode, many components like the DB and API will only ever run in Docker, and you should always make sure that any implementations work within docker. + +Running in the native/local approach may require additional packages to be installed on your machine to get working. + +### Prerequisites + +1. Install the version of Python specified in [pyproject.toml](../../api/pyproject.toml) + [pyenv](https://github.com/pyenv/pyenv#installation) is one popular option for installing Python, + or [asdf](https://asdf-vm.com/). + - If using pyenv run `pyenv local ` to ensure that version will be used in subsequent steps +2. Ensure that `python -V` and `python3 -V` are picking up that version. + - If not, run `pyenv init -` and/or restart your shell to ensure it was run automatically +3. After installing and activating the right version of Python, install + [poetry](https://python-poetry.org/docs/#installation) and follow the instructions to add poetry to your path if necessary. + + ```bash + curl -sSL https://install.python-poetry.org | python3 - + ``` + +4. You'll also need [Docker Desktop](https://www.docker.com/products/docker-desktop/) + +**Note:** All the following commands should be run from the `/api` directory. + +### Database setup: Run Migrations/Seeds + +If you haven't done local development before you'll need to execute the migrations and seed the DB with data using the steps in [database-local-usage.md](database/database-local-usage.md) + +### Services + +Individual services can be run through Docker, which can be useful in concert with non-Docker application development: + +* **OpenSearch** + * Run `make init-opensearch` setup the OpenSearch Container + * Run `make populate-search-opportunities` to push data previously seeded in the DB into the search index + + If your DB or OpenSearch end up in an odd place, you can reset all the persistent storage using `make volume-recreate`. + +* **Localstack (local s3)** + * Run `make init-localstack` +* **Mock OAuth server** + * Run `make init-mock-oath2` + ## Next steps Now that you're up and running, read the [application docs](../../api/README.md) to familiarize yourself with the application. diff --git a/documentation/frontend/authentication.md b/documentation/frontend/authentication.md new file mode 100644 index 000000000..e69de29bb diff --git a/documentation/frontend/development.md b/documentation/frontend/development.md new file mode 100644 index 000000000..a1bd105c5 --- /dev/null +++ b/documentation/frontend/development.md @@ -0,0 +1,86 @@ +# Development + +This [Next.js](https://nextjs.org) application can be run natively (or locally) + +**Running in locally is the default**, but it can be useful to run the built images in order to troubleshoot and to connect directly with the local API application for development. + +## Local (non-Docker) + +Run `npm install && npm run dev` to start the application. + +### Testing "built" version locally + +The Next.js frontend application is exported for production using [next build](https://nextjs.org/docs/app/api-reference/cli/next#next-build-options). To recreate this locally, outside of the container, run the following: + +- `npm run build` - Builds the production Next.js bundle +- `npm start` - Runs the Next.js server, after building the production bundle + +### Search and Opportunity Pages + +The `/search` and opportunity pages rely on the application API. The API endpoint and authenticaion token are defined in `.env.development` and can be overwritten in an `.env.ocal` file. + +Update the `API_URL` can be set to connect to prod (`https://api.simpler.grants.gov`) or lower environment URLs to quickly develop using production or development data. This requires the correct `API_AUTH_TOKEN` variable to be set correctly. + +To connect to the development version of the API, run `make init && db-seed-local && populate-search-opportunities` in the `/api` folder. + +See [documentation/api/development.md](../api/development.md) for more details. + +### Authentication + +Running authentication locally requires running the API, directing the API redirect to the frontend, and sharing the correct JWT keys. + +1. Run `make setup-env-override-file` to create the `override.env` file in the `/api` folder +2. Copy the `API_JWT_PUBLIC_KEY` value from `/api/override.env` file to `/frontend/.env.local` file which creates the necessary keys +3. Add `LOGIN_FINAL_DESTINATION=http://localhost:3000/api/auth/callback` to the `api/override.env` so the API redirects to the correct callback route +4. Start the API and frontend for development + +#### Secrets + +Some functionality will not work locally without supplying the application environment variables containing secrets. + +- New Relic + - `NEW_RELIC_APP_NAME` + - `NEW_RELIC_LICENSE_KEY` +- Email subscription form (Sendy) + - `SENDY_API_KEY` + - `SENDY_API_URL` + - `SENDY_LIST_ID` + +If you need to access this functionality locally, contact an engineer on the team to get access to the necessary secrets. + +### +Docker + +#### Development version + +Alternatively, you can run the application in a Docker container. + +**Note**: If you are running docker locally for the first time, you need to run the API locally through Docker as well, in order to create the required `api_grants_backend` network. + +From the `/frontend` directory: + +1. Run the local development server + ```bash + make dev + ``` +1. Navigate to [localhost:3000](http://localhost:3000) to view the application + +- If installing new packages locally with npm and using `make dev` with docker to run locally, you may need to run `make build` first to bring the new packages into the container + +#### Production version + +The `make dev` command runs the `docker-compose.yml` which runs the `dev` target in the [Dockerfile](./Dockerfile). To run a production version in docker, run `docker compose up -d -f docker-compose-realease.yml` which targest the `release` stage in the docker build. This runs the production version, while still creating a network connection to the local API. + +#### Testing Release Target Locally + +To test the release target locally, run: + +- `make release-build OPTS="--tag [IMAGE_NAME]"` or +- `docker buildx build --target release --tag [IMAGE_NAME]` for a faster build on OSX + +to build a local image. To view the site at `localhost:3000`, run: `docker run -e "HOSTNAME=0.0.0.0" -p 3000:3000 [IMAGE_NAME]`. + +### Search and Opportunity Pages + +The search page and opportunity pages needs additional setup to test locally. + +To diff --git a/frontend/src/services/auth/README.md b/frontend/src/services/auth/README.md deleted file mode 100644 index 858d79902..000000000 --- a/frontend/src/services/auth/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# User Auth - -### Notes - -- Server components can't write cookies, but middleware, route handlers and server actions can. - -### Login flow - -- user clicks "login" - - client side component directs users to /api link -- user comes back with a simpler JWT to /auth/callback - - verifies JWT - - sets cookie -- useUser / UserProvider - - checks cookie / API (see diagram) - -```mermaid -flowchart TD - checkCookie[Check cookie] - cookieExists{Cookie Exists?} - useUser/UserProvider --> checkCookie - cookieValid{Cookie is Valid} - redirectToLogin[redirect to login] - - checkCookie --> cookieExists - cookieExists --> |Yes| cookieValid - cookieExists --> |No| redirectToLogin - cookieValid --> |Yes| d[Return User Data] - cookieValid --> |No| redirectToLogin - -``` - -## Next step - -```mermaid -flowchart TD - checkCookie[Check cookie] - cookieExists{Cookie Exists?} - useUser/UserProvider --> checkCookie - cookieValid{Cookie is Valid} - cookieIsCurrent{Cookie is Current} - redirectToLogin[redirect to login] - - checkCookie --> cookieExists - cookieExists --> |Yes| cookieValid - cookieExists --> |No| redirectToLogin - cookieValid --> |Yes| cookieIsCurrent - cookieValid --> |No | redirectToLogin - cookieIsCurrent --> |Yes| d[Return User Data] - cookieIsCurrent --> |No| e{User exists with session from /api/user} - e --> |Yes| f[set cookie] - e --> |No| redirectToLogin - -``` From a3bd9f9c646cb4c5f2f8ff4d575ddee6aad457b7 Mon Sep 17 00:00:00 2001 From: Aaron Couch Date: Mon, 13 Jan 2025 11:42:44 -0500 Subject: [PATCH 2/6] Update development.md --- documentation/frontend/development.md | 205 +++++++++++++++++++++----- 1 file changed, 167 insertions(+), 38 deletions(-) diff --git a/documentation/frontend/development.md b/documentation/frontend/development.md index a1bd105c5..42c85d5d8 100644 --- a/documentation/frontend/development.md +++ b/documentation/frontend/development.md @@ -6,15 +6,175 @@ This [Next.js](https://nextjs.org) application can be run natively (or locally) ## Local (non-Docker) -Run `npm install && npm run dev` to start the application. +### 🏗️ Development version -### Testing "built" version locally +Run `npm install && npm run dev` to install and start the application. + +### 🏛️ "Built" version The Next.js frontend application is exported for production using [next build](https://nextjs.org/docs/app/api-reference/cli/next#next-build-options). To recreate this locally, outside of the container, run the following: - `npm run build` - Builds the production Next.js bundle - `npm start` - Runs the Next.js server, after building the production bundle +## Docker + +### 🏗️ Development version + +Alternatively, you can run the application in a Docker container. + +**Note**: If you are running docker locally for the first time, you need to run the API locally through Docker as well, in order to create the required `api_grants_backend` network. + +From the `/frontend` directory: + +1. Run the local development server + ```bash + make dev + ``` +1. Navigate to [localhost:3000](http://localhost:3000) to view the application + +- If installing new packages locally with npm and using `make dev` with docker to run locally, you may need to run `make build` first to bring the new packages into the container + +### 🚀 Production version + +The `make dev` command runs the `docker-compose.yml` which runs the `dev` target in the [Dockerfile](./Dockerfile). To run a production version in docker, run `docker compose up -d -f docker-compose-realease.yml` which targest the `release` stage in the docker build. This runs the production version, while still creating a network connection to the local API. + +### Testing Release Target Locally + +To test the release target locally, run: + +- `make release-build OPTS="--tag [IMAGE_NAME]"` or +- `docker buildx build --target release --tag [IMAGE_NAME]` for a faster build on OSX + +to build a local image. To view the site at `localhost:3000`, run: `docker run -e "HOSTNAME=0.0.0.0" -p 3000:3000 [IMAGE_NAME]`. + +## 🎯 Testing + +### :atom: Unit Testing + +[Jest](https://jestjs.io/docs/getting-started) is used as the test runner and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) 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](https://jestjs.io/docs/cli#--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/`: + +```sh +npm run test-watch -- pages +``` + +### 🚦 End-to-end (E2E) testing + +[Playwright](https://playwright.dev/) is a framework for web testing and its test runner is called [Playwright Test](https://playwright.dev/docs/api/class-test), which can be used to run E2E or integration tests across chromium, firefox, and webkit browsers. + +E2E test filenames end with `.spec.ts` and are found in the `tests/e2e` directory. + +To run E2E tests via CLI: + +- `cd ../api && make init db-seed-local start` (prerequisite to start the API) +- `npx playwright install --with-deps` — Downloads playwright browsers required to run tests +- `npm run test:e2e` — Runs all E2E tests using the playwright config found at `tests/playwright.config.ts` +- `npm run test:e2e:ui` — Run specific or all E2E tests using Playwright's [UI mode](https://playwright.dev/docs/test-ui-mode), which is useful for debugging full traces of each test + +To run E2E tests using VS Code: + +1. Download the VS Code extension described in these [Playwright docs](https://playwright.dev/docs/running-tests#run-tests-in-vs-code) +2. Follow the [instructions](https://playwright.dev/docs/getting-started-vscode#running-tests) Playwright provides + +Playwright E2E tests run "local-to-local", requiring both the frontend and the API to be running for the tests to pass - and for the database to be seeded with data. + +In CI, the "Front-end Checks" workflow (`.github/workflows/ci-frontend-e2e.yml`) summary will include an "Artifacts" section where there is an attached "playwright-report". [Playwright docs](https://playwright.dev/docs/ci-intro#html-report) describe how to view HTML Report in more detail. + +### 🤖 Type checking, linting, and formatting + +#### Tools + +- [TypeScript](https://www.typescriptlang.org/) is used for type checking. +- [ESLint](https://eslint.org/) is used for linting. This helps catch common mistakes and encourage best practices. +- [Prettier](https://prettier.io/) is used for code formatting. This reduces the need for manual formatting or nitpicking and enforces a consistent style.PRs in Github Actions, other than e2e tests + +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](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) and [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) extensions. +2. Add the following to a `.vscode/settings.json` Workspace Settings file: + + ```json + { + "editor.codeActionsOnSave": { + "source.fixAll.eslint": true + }, + "editor.formatOnSave": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "eslint.workingDirectories": ["./frontend"], + "typescript.validate.enable": true + } + ``` + + For these tools to auto run, the settings must be located in the root of your current VSCode workspace. For example, if you open the `frontend/` directory in VSCode, the settings should be located at `frontend/.vscode/settings.json`. If you then open then root repository directory in VSCode as your workspace, these tools will not auto run. (Note that adding the settings to the root repository directory may affect other parts of a monorepo.) + + You can alternatively add the settings to your User Settings, however they will apply globally to any workspace you open. See [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings) for more guidance. + +
+ +#### NPM Scripts for type checking, linting, and formatting + +- `npm run ts:check` - Type checks all files +- `npm run lint` - Lints all files and reports any errors +- `npm run lint-fix` - Lints all files and fixes any auto-fixable errors +- `npm run format`: Formats all files based on prettier rules +- `npm run format-check`: Check files for prettier formatting violations without fixing them +- `npm run all-checks`: Runs linting, typescript check, unit testing, and creates a build - simulating locally tests that are run on PRs in Github Actions, other than e2e tests + +### 🖼️ Storybook + +Storybook is a [frontend workshop](https://bradfrost.com/blog/post/a-frontend-workshop-environment/) 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. + +See the [Storybook Next.js documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks/nextjs) for more information about using Storybook with Next.js + +Similar to the Next.js application, Storybook can be ran natively or in a Docker container. + +#### Native + +From the `frontend/` directory: + +1. `npm run storybook` +2. Navigate to [localhost:6006](http://localhost:6006) to view + +#### Static + +- `npm run storybook-build` - Exports a static site to `storybook-static/` + +#### Docker + +Alternatively, you can run Storybook in a Docker container. + +From the `frontend/` directory: + +1. `make storybook` +2. Navigate to [localhost:6006](http://localhost:6006) to view + +### 🐛 Debugging the Next App in VSCode + +- See the debug config: `./.vscode/launch.json` + - There are several debug config targets defined there depending on if you want to debug just client components (client-side), just server components (server-side), or both (with the Full Stack option). You can also debug the built server (launched from `npm start` instead of `npm run dev`). +- Run one of these launch targets from the VSCode debug menu +- Place breakpoints in VSCode +- Visit the relevant routes in the browser and confirm you can hit these breakpoints + +**Note** that debugging the server-side or full-stack here doesn't debug the API. [See the API readme for more information](../documentation/api/development.md) + +## Feature setup and development + +The following features require additional local setup to use. + ### Search and Opportunity Pages The `/search` and opportunity pages rely on the application API. The API endpoint and authenticaion token are defined in `.env.development` and can be overwritten in an `.env.ocal` file. @@ -34,7 +194,7 @@ Running authentication locally requires running the API, directing the API redir 3. Add `LOGIN_FINAL_DESTINATION=http://localhost:3000/api/auth/callback` to the `api/override.env` so the API redirects to the correct callback route 4. Start the API and frontend for development -#### Secrets +### New Relic and Sendy (email) Some functionality will not work locally without supplying the application environment variables containing secrets. @@ -48,39 +208,8 @@ Some functionality will not work locally without supplying the application envir If you need to access this functionality locally, contact an engineer on the team to get access to the necessary secrets. -### +Docker - -#### Development version - -Alternatively, you can run the application in a Docker container. - -**Note**: If you are running docker locally for the first time, you need to run the API locally through Docker as well, in order to create the required `api_grants_backend` network. - -From the `/frontend` directory: - -1. Run the local development server - ```bash - make dev - ``` -1. Navigate to [localhost:3000](http://localhost:3000) to view the application - -- If installing new packages locally with npm and using `make dev` with docker to run locally, you may need to run `make build` first to bring the new packages into the container - -#### Production version - -The `make dev` command runs the `docker-compose.yml` which runs the `dev` target in the [Dockerfile](./Dockerfile). To run a production version in docker, run `docker compose up -d -f docker-compose-realease.yml` which targest the `release` stage in the docker build. This runs the production version, while still creating a network connection to the local API. - -#### Testing Release Target Locally - -To test the release target locally, run: - -- `make release-build OPTS="--tag [IMAGE_NAME]"` or -- `docker buildx build --target release --tag [IMAGE_NAME]` for a faster build on OSX - -to build a local image. To view the site at `localhost:3000`, run: `docker run -e "HOSTNAME=0.0.0.0" -p 3000:3000 [IMAGE_NAME]`. - -### Search and Opportunity Pages - -The search page and opportunity pages needs additional setup to test locally. +## Other topics -To +- [Internationalization](../documentation/frontend/internationalization.md) +- [Feature Flags](../documentation/frontend/featureFlags.md) +- Refer to the [architecture decision records](../documentation/decisions) for more context on technical decisions. From d102e4c84d389461f3d32f3b94ec8813bc016749 Mon Sep 17 00:00:00 2001 From: Aaron Couch Date: Mon, 13 Jan 2025 11:46:00 -0500 Subject: [PATCH 3/6] Update README.md --- frontend/README.md | 186 ++++----------------------------------------- 1 file changed, 15 insertions(+), 171 deletions(-) diff --git a/frontend/README.md b/frontend/README.md index 9ebd01b52..5dd6513f9 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,4 +1,6 @@ -# Overview +# Application Documentation + +## Introduction - This is a [Next.js](https://nextjs.org/) React web application, written in [TypeScript](https://www.typescriptlang.org/). - [U.S. Web Design System](https://designsystem.digital.gov) provides themeable styling and a set of common components. @@ -20,16 +22,12 @@ └── tests # Unit and E2E tests ``` -# 💻 Development +## 💻 Local Development [Next.js](https://nextjs.org/docs) provides the React framework for building the web application. Pages are defined in the `app/` directory. Pages are automatically routed based on the file name. For example, `pages/[locale]/page.tsx` is the home page. [**Learn more about developing Next.js applications** ↗️](https://nextjs.org/docs) -## Getting started - -The application can be run natively or in a Docker container. - ### Running the app locally Before running the server, duplicate the `/frontend/env.development` file and name the copy `/frontend/.env.local`, in order to avoid checking in any sensitive data to Github. @@ -50,175 +48,21 @@ From the `/frontend` directory: ``` 1. Navigate to [localhost:3000](http://localhost:3000) to view the application -#### Secrets - -Some functionality will not work locally without supplying the application environment variables containing secrets. - -- New Relic - - `NEW_RELIC_APP_NAME` - - `NEW_RELIC_LICENSE_KEY` -- Email subscription form (Sendy) - - `SENDY_API_KEY` - - `SENDY_API_URL` - - `SENDY_LIST_ID` - -If you need to access this functionality locally, contact an engineer on the team to get access to the necessary secrets. - -#### Other scripts +### Other scripts - `npm run build` - Builds the production Next.js bundle - `npm start` - Runs the Next.js server, after building the production bundle -### Running the app in Docker - -Alternatively, you can run the application in a Docker container. - -From the `/frontend` directory: - -1. Run the local development server - ```bash - make dev - ``` -1. Navigate to [localhost:3000](http://localhost:3000) to view the application - -- If installing new packages locally with npm and using `make dev` with docker to run locally, you may need to run `make build` first to bring the new packages into the container - -**Note:** To run the fully integrated app, with the Next JS app connecting to the API, uncomment the correct environment variable for the API_URL in your .env.development or .env.local file, and run `make start` in the API directory before starting your local frontend container. - -#### Testing Release Target Locally - -To test the release target locally, run: - -- `make release-build OPTS="--tag [IMAGE_NAME]"` or -- `docker buildx build --target release --tag [IMAGE_NAME]` for a faster build on OSX - -to build a local image. To view the site at `localhost:3000`, run: `docker run -e "HOSTNAME=0.0.0.0" -p 3000:3000 [IMAGE_NAME]`. - -# 🖼️ Storybook - -Storybook is a [frontend workshop](https://bradfrost.com/blog/post/a-frontend-workshop-environment/) 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. - -See the [Storybook Next.js documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks/nextjs) for more information about using Storybook with Next.js - -Similar to the Next.js application, Storybook can be ran natively or in a Docker container. - -## Native - -From the `frontend/` directory: - -1. `npm run storybook` -2. Navigate to [localhost:6006](http://localhost:6006) to view - -### Other scripts - -- `npm run storybook-build` - Exports a static site to `storybook-static/` - -## Docker - -Alternatively, you can run Storybook in a Docker container. - -From the `frontend/` directory: - -1. `make storybook` -2. Navigate to [localhost:6006](http://localhost:6006) to view - -# Testing - -## 🐛 Unit Testing - -[Jest](https://jestjs.io/docs/getting-started) is used as the test runner and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) 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](https://jestjs.io/docs/cli#--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/`: - -```sh -npm run test-watch -- pages -``` - -## 🚦 End-to-end (E2E) testing - -[Playwright](https://playwright.dev/) is a framework for web testing and its test runner is called [Playwright Test](https://playwright.dev/docs/api/class-test), which can be used to run E2E or integration tests across chromium, firefox, and webkit browsers. - -E2E test filenames end with `.spec.ts` and are found in the `tests/e2e` directory. - -To run E2E tests via CLI: - -- `cd ../api && make init db-seed-local start` (prerequisite to start the API) -- `npx playwright install --with-deps` — Downloads playwright browsers required to run tests -- `npm run test:e2e` — Runs all E2E tests using the playwright config found at `tests/playwright.config.ts` -- `npm run test:e2e:ui` — Run specific or all E2E tests using Playwright's [UI mode](https://playwright.dev/docs/test-ui-mode), which is useful for debugging full traces of each test - -To run E2E tests using VS Code: - -1. Download the VS Code extension described in these [Playwright docs](https://playwright.dev/docs/running-tests#run-tests-in-vs-code) -2. Follow the [instructions](https://playwright.dev/docs/getting-started-vscode#running-tests) Playwright provides - -Playwright E2E tests run "local-to-local", requiring both the frontend and the API to be running for the tests to pass - and for the database to be seeded with data. - -In CI, the "Front-end Checks" workflow (`.github/workflows/ci-frontend-e2e.yml`) summary will include an "Artifacts" section where there is an attached "playwright-report". [Playwright docs](https://playwright.dev/docs/ci-intro#html-report) describe how to view HTML Report in more detail. - -## 🤖 Type checking, linting, and formatting - -### Tools - -- [TypeScript](https://www.typescriptlang.org/) is used for type checking. -- [ESLint](https://eslint.org/) is used for linting. This helps catch common mistakes and encourage best practices. -- [Prettier](https://prettier.io/) is used for code formatting. This reduces the need for manual formatting or nitpicking and enforces a consistent style.PRs in Github Actions, other than e2e tests - -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](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) and [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) extensions. -2. Add the following to a `.vscode/settings.json` Workspace Settings file: - - ```json - { - "editor.codeActionsOnSave": { - "source.fixAll.eslint": true - }, - "editor.formatOnSave": true, - "editor.defaultFormatter": "esbenp.prettier-vscode", - "eslint.workingDirectories": ["./frontend"], - "typescript.validate.enable": true - } - ``` - - For these tools to auto run, the settings must be located in the root of your current VSCode workspace. For example, if you open the `frontend/` directory in VSCode, the settings should be located at `frontend/.vscode/settings.json`. If you then open then root repository directory in VSCode as your workspace, these tools will not auto run. (Note that adding the settings to the root repository directory may affect other parts of a monorepo.) - - You can alternatively add the settings to your User Settings, however they will apply globally to any workspace you open. See [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings) for more guidance. - -
- -### NPM Scripts for type checking, linting, and formatting - -- `npm run ts:check` - Type checks all files -- `npm run lint` - Lints all files and reports any errors -- `npm run lint-fix` - Lints all files and fixes any auto-fixable errors -- `npm run format`: Formats all files based on prettier rules -- `npm run format-check`: Check files for prettier formatting violations without fixing them -- `npm run all-checks`: Runs linting, typescript check, unit testing, and creates a build - simulating locally tests that are run on PRs in Github Actions, other than e2e tests - -# Debugging the Next App in VSCode - -- See the debug config: `./.vscode/launch.json` - - There are several debug config targets defined there depending on if you want to debug just client components (client-side), just server components (server-side), or both (with the Full Stack option). You can also debug the built server (launched from `npm start` instead of `npm run dev`). -- Run one of these launch targets from the VSCode debug menu -- Place breakpoints in VSCode -- Visit the relevant routes in the browser and confirm you can hit these breakpoints +## Testing and feature development -**Note** that debugging the server-side or full-stack here doesn't debug the API. [See the API readme for more information](../documentation/api/development.md) +See [development.md](../documentation/frontend/development.md) for full installation and development instructions. -# Other topics +## Technical information -- [Internationalization](../documentation/frontend/internationalization.md) -- [Feature Flags](../documentation/frontend/featureFlags.md) -- Refer to the [architecture decision records](../documentation/decisions) for more context on technical decisions. +* [Architecture diagram](../documentation/architecture/README.md) +* [Authentication overview](../documentation/api/authentication.md) +* [Authentication local setup](../documentation/frontend/development.md#authentication) +* [Testing](../documentation/frontend/development.md#testing) +* [Type checking, linting, and formatting](../documentation/frontend/development.md##-type-checking-linting-and-formatting) +* [Search and opportunity page local setup](../documentation/frontend/development.md#search-and-opportunity-pages) + From e993966f8f7247610e26252c38a262ce208e6709 Mon Sep 17 00:00:00 2001 From: acouch Date: Mon, 13 Jan 2025 11:48:24 -0500 Subject: [PATCH 4/6] Remove empty file --- documentation/frontend/authentication.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 documentation/frontend/authentication.md diff --git a/documentation/frontend/authentication.md b/documentation/frontend/authentication.md deleted file mode 100644 index e69de29bb..000000000 From dd2d4640da443a4ba46e43eccb71fcdb535c0bd5 Mon Sep 17 00:00:00 2001 From: Aaron Couch Date: Mon, 13 Jan 2025 11:53:31 -0500 Subject: [PATCH 5/6] Update README.md --- frontend/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/frontend/README.md b/frontend/README.md index 5dd6513f9..5d5621c02 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -62,7 +62,7 @@ See [development.md](../documentation/frontend/development.md) for full installa * [Architecture diagram](../documentation/architecture/README.md) * [Authentication overview](../documentation/api/authentication.md) * [Authentication local setup](../documentation/frontend/development.md#authentication) -* [Testing](../documentation/frontend/development.md#testing) -* [Type checking, linting, and formatting](../documentation/frontend/development.md##-type-checking-linting-and-formatting) +* [Testing](../documentation/frontend/development.md#-testing) +* [Type checking, linting, and formatting](../documentation/frontend/development.md#-type-checking-linting-and-formatting) * [Search and opportunity page local setup](../documentation/frontend/development.md#search-and-opportunity-pages) From 84828d952ac7282cba525963ee73b981a2085376 Mon Sep 17 00:00:00 2001 From: acouch Date: Mon, 13 Jan 2025 11:59:14 -0500 Subject: [PATCH 6/6] Update README.md for formatting --- frontend/README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/frontend/README.md b/frontend/README.md index 5d5621c02..06c5c89bb 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -59,10 +59,9 @@ See [development.md](../documentation/frontend/development.md) for full installa ## Technical information -* [Architecture diagram](../documentation/architecture/README.md) -* [Authentication overview](../documentation/api/authentication.md) -* [Authentication local setup](../documentation/frontend/development.md#authentication) -* [Testing](../documentation/frontend/development.md#-testing) -* [Type checking, linting, and formatting](../documentation/frontend/development.md#-type-checking-linting-and-formatting) -* [Search and opportunity page local setup](../documentation/frontend/development.md#search-and-opportunity-pages) - +- [Architecture diagram](../documentation/architecture/README.md) +- [Authentication overview](../documentation/api/authentication.md) +- [Authentication local setup](../documentation/frontend/development.md#authentication) +- [Testing](../documentation/frontend/development.md#-testing) +- [Type checking, linting, and formatting](../documentation/frontend/development.md#-type-checking-linting-and-formatting) +- [Search and opportunity page local setup](../documentation/frontend/development.md#search-and-opportunity-pages)