Recidiviz Dashboards

End user web applications built on top of the Recidiviz data platform.

Overview

This repo uses the Nx integrated monorepo pattern to support a number of separate modules and applications that can be used together or separately. Nx provides a lot of tooling that we will not discuss in detail here but that we may use routinely for development or CI; you are encouraged to spend some time with the Nx docs and get familiar with its core features. We generally aspire to stick to (or migrate towards) the default ways of doing things in Nx; e.g., using standard plugins for common tasks, adopting the typical folder structure, etc.

Code in this repo is organized into projects, which are the main unit of code organization in Nx. In practice a project in Nx is just a folder with a project.json config file in it, and import statements can freely cross project boundaries (except as restricted by linting rules). Refer to the README for a given project for more detailed information about how to use it and develop on it.

Application projects (a project in Nx ) (found in apps/**) are the primary entry points for the applications contained in this codebase, but projects may be added to other subfolders as well as the codebase evolves.

Development

Getting set up

1. Grab the source:

   git clone https://github.com/Recidiviz/pulse-dashboards.git

2. Ensure you are using the correct version of Node (if you don't use NVM, just check the .nvmrc file and ensure you are using that version).

   nvm use

3. Install Yarn package manager:

   brew install yarn

   For alternative Yarn installation options, see Yarn Installation.

4. Install dependencies:

   yarn install

5. Additional recommendations:

   1. Install Nx globally (convenient for running package scripts): yarn global add nx@latest
   2. Install a linting package for your preferred code editor that hooks into ESLint, such as the ESLint extension for VS Code.
   3. Install a formatting package for your preferred code editor that hooks into Prettier, such as the Prettier - Code Formatter extension for VS Code.
   4. Install the Nx Console for your code editor if you prefer a GUI for exploring and using Nx.
   5. To make git blame more informative, tell it to ignore reformatting commits by running git config blame.ignorerevsfile .git-blame-ignore-revs.

Creating new libraries

Why make a library?

One of the core concepts of Nx is the idea of organizing your code into libraries, and putting most of your code into libraries rather than apps. While it may be a scary and overloaded word, in Nx parlance a "library" is basically just a folder with an Nx config file in it (usually project.json). This lets Nx include that directory in its "project graph", which it uses to model the dependencies between different projects in the repo.

Briefly stated, there are a few benefits to doing this:

• Allows us to only run tasks like lint and test when there are changes affecting that project, via nx affectedin CI or even just during development via nx test [your-project]
• Allows us to have more fine-grained control over which features can depend on which other features, via the Nx enforce-module-boundaries linting package.

How to make a library

TL;DR: run nx generate ~repo:lib [my-library] and follow the prompts. Update the generated files as necessary.

Long version: Nx has various plugins that automate the boilerplate and nuances of creating and configuring libraries, such as @nx/js and @nx/react. You can use those directly when needed, but in most cases you will want to reach for our local plugin first, which extends those plugins by setting our preferred options and extending the default plugin outputs with additional configuration and features that are tailored to our applications. These are meant to be sensible defaults, you can always override or extend them as needed to suit your use case. See /plugins/repo to learn more about its implementation.