{"id":22538046,"url":"https://github.com/cfpb/hmda-frontend","last_synced_at":"2026-02-02T22:32:40.787Z","repository":{"id":38066457,"uuid":"212168767","full_name":"cfpb/hmda-frontend","owner":"cfpb","description":"Collection of HMDA frontend apps","archived":false,"fork":false,"pushed_at":"2025-06-24T12:27:48.000Z","size":680419,"stargazers_count":16,"open_issues_count":74,"forks_count":20,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-06-24T13:21:49.354Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfpb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-10-01T18:23:14.000Z","updated_at":"2025-06-24T12:11:58.000Z","dependencies_parsed_at":"2023-10-13T08:38:44.965Z","dependency_job_id":"c91ef03a-8705-470f-9580-2051050d42b2","html_url":"https://github.com/cfpb/hmda-frontend","commit_stats":null,"previous_names":[],"tags_count":145,"template":false,"template_full_name":"cfpb/open-source-project-template","purl":"pkg:github/cfpb/hmda-frontend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fhmda-frontend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fhmda-frontend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fhmda-frontend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fhmda-frontend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfpb","download_url":"https://codeload.github.com/cfpb/hmda-frontend/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfpb%2Fhmda-frontend/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266708514,"owners_count":23971946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-07T11:09:54.511Z","updated_at":"2026-02-02T22:32:40.781Z","avatar_url":"https://github.com/cfpb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HMDA Frontend Projects\n\n![Static Badge](https://img.shields.io/badge/coverage-95%25-green)\n\nThe 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.\n\n## Contents\n\n- [HMDA Frontend Projects](#hmda-frontend-projects)\n  - [Contents](#contents)\n  - [Technical Overview](#technical-overview)\n  - [Applications](#applications)\n    - [HMDA Homepage](#hmda-homepage)\n    - [HMDA Filing](#hmda-filing)\n      - [HMDA User Profile](#hmda-user-profile)\n    - [HMDA Data Browser](#hmda-data-browser)\n    - [HMDA Platform Tools](#hmda-platform-tools)\n    - [HMDA Documentation](#hmda-documentation)\n    - [HMDA Data Publication](#hmda-data-publication)\n    - [HMDA Data Publication - HMDA News and Updates](#hmda-data-publication---hmda-news-and-updates)\n  - [Development](#development)\n    - [Requirements](#requirements)\n    - [Installation](#installation)\n    - [Running Locally](#running-locally)\n      - [Integrating with the Filing application](#integrating-with-the-filing-application)\n        - [Create Institutions](#create-institutions)\n        - [Bypass API Authentication](#bypass-api-authentication)\n        - [Configure the UI](#configure-the-ui)\n      - [Updating or Previewing Documentation](#updating-or-previewing-documentation)\n    * [Running via Docker](#running-via-docker)\n    * [Code Formatting](#code-formatting)\n  - [Creating and editing Markdown](https://github.com/cfpb/hmda-frontend/wiki/Creating-and-updating-Markdown-files)\n  - [Adding GIFs](#adding-gifs)\n  * [Testing](#testing)\n    - [Unit Tests](#unit-tests)\n    - [End-to-End Testing](#end-to-end-testing)\n    - [Running in TravisCI](#running-in-travisci)\n\n## Technical Overview\n\nEach 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](https://reacttraining.com/react-router/) is used for client side routing with [React Redux](https://redux.js.org/) integrated for state management of the more complex apps, such as Filing. [Unit tests](#unit-tests) are developed using Enzyme and [end-to-end](#end-to-end-testing) testing performed with Cypress. Dependencies are managed with [yarn](https://yarnpkg.com/getting-started).\n\n## Applications\n\n### HMDA Homepage\n\n[HMDA Homepage](https://ffiec.cfpb.gov/) is a single-page app providing easy access to the HMDA applications, tools, data products, and documentation.\n\n\u003ca href='./readme-files/hmda-homepage.png' alt='HMDA Homepage'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-homepage.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n### HMDA Filing\n\nThe [HMDA Filing Platform UI](https://ffiec.cfpb.gov/filing/) allows lending institutions to submit HMDA records, resolve errors, verify edits, review submission status and history, and sign submissions.\n\n\u003ca href='./readme-files/hmda-filing.png' alt='HMDA Filing Overview'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-filing.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n#### HMDA User Profile\n\nThe [HMDA Profile page](https://ffiec.cfpb.gov/filing/profile) 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.\n\n\u003ca href='./readme-files/hmda-completeprofile.png' alt='HMDA User Profile Information'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-completeprofile.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n### HMDA Data Browser\n\nThe [HMDA Data Browser](https://ffiec.cfpb.gov/data-browser/) enables users to easily filter and download aggregated HMDA datasets.\n\n\u003ca href='./readme-files/hmda-data-browser.gif' alt='HMDA Data Browser'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-data-browser.gif' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n### HMDA Platform Tools\n\nThe [HMDA Platform Tools](https://ffiec.cfpb.gov/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.\n\n\u003ca href='./readme-files/hmda-tools.png' alt='HMDA Platform Tools'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-tools.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n### HMDA Documentation\n\nThe [HMDA Documentation](https://ffiec.cfpb.gov/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](https://www.algolia.com/) through the [DocSearch](https://docsearch.algolia.com/) program.\n\n\u003ca href='./readme-files/hmda-documentation.png' alt='HMDA Documentation'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-documentation.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n### HMDA Data Publication\n\n[HMDA Data Publication](https://ffiec.cfpb.gov/data-publication/) provides datasets and reports of HMDA data collected in or after 2017 which, combined with [Census](https://www.ffiec.gov/censusproducts.htm) demographic data, can be used for data analysis purposes.\n\n\u003ca href='./readme-files/hmda-data-publication.png' alt='HMDA Data Publication'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-data-publication.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n### HMDA Data Publication - HMDA News and Updates\n\n[Publication HMDA News and Updates](https://ffiec.cfpb.gov/data-publication/updates) provides a searchable change log of updates, releases, and corrections to published HMDA Data. Visit the [HMDA News and Updates FAQ](./src/data-publication/ChangeLog/README.md) for details.\n\n\u003ca href='./readme-files/hmda-data-publication-updates.png' alt='HMDA Data Publication'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/hmda-data-publication-updates.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n## Development\n\n### Requirements\n\n- Node \u003e= v20.8.0\n- Yarn berry \u003e= v4.0.2\n\n### Installation\n\n- Clone repo\n- Run `yarn` from repo root to install depencencies\n\n### Running Locally\n\nSeveral components of the Frontend (ex. Filing, Data Browser) require a connection to the [HMDA Platform](https://github.com/cfpb/hmda-platform) in order to operate. You can find instructions for the running the HMDA Platform locally [here](https://github.com/cfpb/hmda-platform#running-with-sbt).\n\nHMDA Help requires a connection to the [HMDA Institutions API](https://github.com/cfpb/hmda-platform/tree/master/institutions-api) in order to operate. You can find instructions for the running the HMDA Institutions API locally [in the README](https://github.com/cfpb/hmda-platform/blob/master/institutions-api/README.md). Note that having the HMDA Platform running is a pre-requisite to starting the HDMA Institutions API.\n\nIf your development does not require this integration, you can simply:\n\n1. Copy `.env.example` to `.env` and edit the environment variables.\n  - `DEV_URL` is the URL that the frontend app will use for API requests. It should not have a trailing slash.\n  - `MAPBOX_ACCESS_TOKEN` is the access token provided by Mapbox.com for the app's embedded maps. CFPB's token can be found in our [GitHub Enterprise wiki](https://GHE/HMDA-Operations/hmda-devops/wiki/Mapbox-credentials).\n2. Run `yarn start` to start a local development server at http://localhost:3000.\n\n#### Integrating with the Filing application\n\nBy default, the locally running [Frontend is configured to use the Filing API](https://github.com/cfpb/hmda-frontend/blob/master/package.json#L65) from the locally running Platform. In order to go through the Filing process, there are a few elements that need to be completed first:\n\n- Create Institutions (Platform)\n- Bypass API authentication (Platform)\n- Configure the UI (Frontend)\n\n##### Create Institutions\n\nBefore 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:\n\n```\nyarn ci-data\n```\n\nTo create data for an Institution other than the default `FRONTENDTESTBANK9999`, you can modify `cypress/ci/config/institutions.json` and rerun the above command.\n\nThis Institution loading needs to be done each time the HMDA Platform is restarted.\n\n##### Bypass API Authentication\n\nOn 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.\n\n```\nexport HMDA_RUNTIME_MODE=dev\n```\n\n##### Configure the UI\n\nIf you will be testing against an Institution that is not the default, you can configure this via a `VITE_*` variable:\n\n```\nVITE_LEIS=INSTITUTION1,INSTITUTION2\n```\n\nSecond, 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:\n\n```\nyarn ci\n```\n\nTo combine these configuration options\n\n```\nVITE_LEIS=INSTITUTION1,INSTITUTION2 yarn ci\n```\n\nYou can now visit the filing application at http://localhost:3000/filing.\n\n### Running via Docker\n\nTo see the application running in a container you can run:\n\n```\ndocker build --secret id=env_vars,src=.env -t hmda/hmda-frontend .\ndocker run -p 8080:8080 hmda/hmda-frontend\n```\n\n### Build image to run in EKS Cluster\n```\ncp .env.example .env\ngsed -i 's/^.*MAPBOX_ACCESS.*$/MAPBOX_ACCESS_TOKEN=pk.xxx/' .env\ndocker build --build-arg DOCKER_TAG=v3.3.1 --secret id=env_vars,src=.env  -t \u003cAWS_Account\u003e.dkr.ecr.us-east-1.amazonaws.com/hmda/hmda-frontend:v3.3.1\n```\nTo build using docker-compose:\n\n```\ndocker-compose build\n```\n\n### Code Formatting\n\nThe prettier formatting tool the formatter of choice for this repo.\n\nPrettier Format API: https://prettier.io/docs/en/options.html\n\nThe `.prettierrc.json` file contains the specific formatting for each file. \u003cbr /\u003e\nThe `.prettierignore` file will ignore formatting any directories or files listed.\n\nIn order to have `Prettier` properly format the developers code there are a few steps that developer needs to take.\n\n1. Install the `Prettier` code extension\n\n\u003ca href='./readme-files/prettier-extension.png' alt='Prettier Extension Install'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/prettier-extension.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n2. Update the developers Visual Studio Code user settings to use the `Prettier` formatter as the default formatter\n\nFirst 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.\n\n\u003ca href='./readme-files/navigate-settings-json-file.png' alt='Navigate to Settings JSON File'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/navigate-settings-json-file.png' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\nNow we need to add 2 lines of code to our JSON file.\n\n```JSON\n\"editor.defaultFormatter\": \"esbenp.prettier-vscode\",\n\"editor.formatOnSave\": true,\n```\n\nThe newly added lines tell VS Code to use `Prettier` as the default formatter and will format the code when the file is saved.\n\n### Helpful Prettier formatting scripts\n\n#### Running all files:\n\n```\nnpx prettier --write\n```\n\n#### Directory Specific:\n\n```\nnpx prettier --write {enter-directory}\n```\n\n#### Check files formatting:\n\n```\nnpx prettier --check\n```\n\nThe above command will return in the terminal what files have not been formatted by prettier.\n\n#### NOTE: formatting settings that prettier cannot do:\n\n- Format on Paste\n  - `\"editor.formatOnPaste\": true,`\n- Themes\n- Icon Themes\n\n## Adding GIFs\n\nWhy GIFs? GIFs provide a better visual repesentation of how a parituclar part of the UI functions.\n\nExamples that are already in our README\n\n- [HMDA Data Browser](#hmda-data-browser)\n- [End to End Testing](#end-to-end-testing)\n\n### Record video to turn into GIF\n\nNavigate to [Apple support native screenshot \u0026 recording controls](https://support.apple.com/guide/mac-help/take-a-screenshot-mh26782/mac) to learn how to use MacOS controls.\n\n**Create recording bounds** \u003cbr\u003e\nOn 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.\n\nNavigate to [Apple support how to record with QuickTime Player](https://support.apple.com/en-us/102618).\n\n### Convert video file to `.gif`\n\nSmall file size + lower quality [video to gif converter](https://biteable.com/tools/video-to-gif/). \u003cbr\u003e\nLarge file size + higher quality [video to gif converter](https://cloudconvert.com/mov-to-gif).\n\n### Store the GIF in the Frontend\n\nNavigate to the `readme-files` directory and upload the `.gif` extension this directory.\n\n### How to use GIF in README\n\nPaste the below code to the section you want to import your GIF and update the `name-of-gif` pieces.\n\n```HTML\n\u003ca href='./readme-files/name-of-gif.gif' alt='name-of-alt'\u003e\n  \u003cp align='center'\u003e\n    \u003cimg src='./readme-files/name-of-gif.gif' width='80%'  overflow='scroll'/\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n```\n\n## Testing\n\n### Unit Tests\n\nCurrent unit tests use Vitest and can be run with `yarn unit-tests`.\n\nLegacy unit tests use Jest and many of them are outdated/broken.\n\nLegacy unit tests can be run with `yarn unit-tests-legacy`. Many are outdated/broken and have been tagged with `// @broken` at the top of the test file. The yarn script will skip all test files with this tag. To run all legacy unit tests, including broken ones, use `yarn unit-tests-legacy-all`.\n\n### End-to-End Testing\n\n```\nyarn test\n```\n\n[Cypress](https://www.cypress.io/) 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.\n\nWhenever a dependency that affects Cypress is added or upgraded in [`package.json`](package.json), you'll need to make the same change in the `cypress` directory's [`package.json` file](cypress/package.json) and then [update the test image](cypress/README.md#updating-the-test-image).\n\n![Cypress automated filing test](./readme-files/filing-2020-q1-cypress.gif)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfpb%2Fhmda-frontend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfpb%2Fhmda-frontend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfpb%2Fhmda-frontend/lists"}