The HMDA Frontend monorepo hosts the public facing applications for the collection, publication, and navigation of millions of HMDA records per year. This repository combines six, previously separate, React application repos in order to simplify component sharing, synchronize versioning of common dependencies, and improve rendering efficiency when navigating between apps.
- HMDA Frontend Projects
Each React application lives in it's own sub-directory of the /src folder, with shared assets and components housed in /common. All sub-applications are rendered as asynchronous components within an application shell /App.jsx that provides a common header. This approach eliminates unneccesary reloading of the site-wide navigation, giving the separate apps a more connected feel. React Router is used for client side routing with React Redux integrated for state management of the more complex apps, such as Filing. Unit tests are developed using Enzyme and end-to-end testing performed with Cypress. Dependencies are managed with yarn.
HMDA Homepage is a single-page app providing easy access to the HMDA applications, tools, data products, and documentation.
The HMDA Filing Platform UI allows lending institutions to submit HMDA records, resolve errors, verify edits, review submission status and history, and sign submissions.
The HMDA Profile page is designed to update associated institutions with the logged in account. Once the associated institutions have been added to your account, you can now file for those institutions.
The HMDA Data Browser enables users to easily filter and download aggregated HMDA datasets.
The HMDA Platform Tools assist filers in the preparation of submission data, including calculation of Rate Spread, generation and validation of Check Digits, as well as submission file generation and format verification.
The HMDA Documentation site provides product FAQs, detailed Filing instructions, data publication schema and usage guides, as well as direction for using the HMDA Tools. Documentation content is hosted as easily editable Markdown files, loaded using Docusaurus. This allows updates to be pushed to Production without a project redeployment. Docusarus search is powered by Algolia through the DocSearch program.
HMDA Data Publication provides datasets and reports of HMDA data collected in or after 2017 which, combined with Census demographic data, can be used for data analysis purposes.
Publication Updates and Notes provides a searchable change log of updates, releases, and corrections to published HMDA Data. Visit the Updates and Notes FAQ for details.
- Node >= v20.8.0
- Yarn berry >= v4.0.2
- Clone repo
- Run
yarnfrom repo root to install depencencies
Several components of the Frontend (ex. Filing, Data Browser) require a connection to the HMDA Platform in order to operate. You can find instructions for the running the HMDA Platform locally here.
HMDA Help requires a connection to the HMDA Institutions API in order to operate. You can find instructions for the running the HMDA Institutions API locally in the README. Note that having the HMDA Platform running is a pre-requisite to starting the HDMA Institutions API.
If your development does not require this integration, yarn start will run the development server, opening a browser window to http://localhost:3000.
By default, the locally running Frontend is configured to use the Filing API from the locally running Platform. In order to go through the Filing process, there are a few elements that need to be completed first:
- Create Institutions (Platform)
- Bypass API authentication (Platform)
- Configure the UI (Frontend)
Before you can submit a Filing you need to have an Institution created on the Platform for each year you want to test. The following command will generate the required data for the default test Institution, for all currently available filing periods. You need to have the HMDA Platform started before running this command:
yarn ci-data
To create data for an Institution other than the default FRONTENDTESTBANK9999, you can modify cypress/ci/config/institutions.json and rerun the above command.
This Institution loading needs to be done each time the HMDA Platform is restarted.
On the Platform, you will need to set an environment variable to prevent the API from requiring an authentication token for incoming requests. If already running, you will need to restart the Platform.
export HMDA_RUNTIME_MODE=dev
If you will be testing against an Institution that is not the default, you can configure this via a VITE_* variable:
VITE_LEIS=INSTITUTION1,INSTITUTION2
Second, you will need to bypass Frontend authentication. This is most easily done by running the Frontend the way we do in a Continuous Integration environment:
yarn ci
To combine these configuration options
VITE_LEIS=INSTITUTION1,INSTITUTION2 yarn ci
You can now visit the filing application at http://localhost:3000/filing.
To see the application running in a container you can run:
docker build -t hmda/hmda-frontend .
docker run -p 8080:8080 hmda/hmda-frontend
To build using docker-compose:
docker-compose build
The prettier formatting tool the formatter of choice for this repo.
Prettier Format API: https://prettier.io/docs/en/options.html
The .prettierrc.json file contains the specific formatting for each file.
The .prettierignore file will ignore formatting any directories or files listed.
In order to have Prettier properly format the developers code there are a few steps that developer needs to take.
- Install the
Prettiercode extension
- Update the developers Visual Studio Code user settings to use the
Prettierformatter as the default formatter
First open your settings.json file by clicking View at the top of VS Code then click Command Palette and then type what is in the screenshot below.
Now we need to add 2 lines of code to our JSON file.
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,The newly added lines tell VS Code to use Prettier as the default formatter and will format the code when the file is saved.
npx prettier --write
npx prettier --write {enter-directory}
npx prettier --check
The above command will return in the terminal what files have not been formatted by prettier.
- Format on Paste
"editor.formatOnPaste": true,
- Themes
- Icon Themes
Why GIFs? GIFs provide a better visual repesentation of how a parituclar part of the UI functions.
Examples that are already in our README
Navigate to Apple support native screenshot & recording controls to learn how to use MacOS controls.
Create recording bounds
On your Mac, press Shift-Command-5 (or use Launchpad) to open Screenshot and display the tools. Drag the bounds to be where it needs to be for recording the video.
Navigate to Apple support how to record with QuickTime Player.
Small file size + lower quality video to gif converter.
Large file size + higher quality video to gif converter.
Navigate to the readme-files directory and upload the .gif extension this directory.
Paste the below code to the section you want to import your GIF and update the name-of-gif pieces.
<a href='./readme-files/name-of-gif.gif' alt='name-of-alt'>
<p align='center'>
<img src='./readme-files/name-of-gif.gif' width='80%' overflow='scroll'/>
</p>
</a>yarn test
Enzyme enables isolated testing of React components. Unit tests providing verification of feature implementation while also serving as suite of regression tests.
yarn run cypress run
Cypress is used to perform end-to-end testing of the filing application, tools, data publication products, and data browser. It mimicks a user's interaction with the site and allows for rapid, automated system validation of project deployments.
