Spotlight

This repository contains npm packages related to our Spotlight data publishing product, as well as some shared configuration and tooling that involves multiple packages.

Packages in this repository

More information about how to use each individual package can be found in their respective README files.

Spotlight API

A thin Node/Express backend that serves data for the Spotlight website.

Spotlight Client

A React application for the Spotlight website frontend.

Development

Getting set up

First, build the app locally.

1. Grab the source:

   git clone git@github.com:Recidiviz/public-dashboard.git

2. Install Yarn package manager:

   brew install yarn

   For alternative Yarn installation options, see Yarn Installation.

3. Install dependencies:

   yarn install

That's it! We suggest installing a linting package for your preferred code editor that hooks into eslint. (Note that you may need to configure your linting plugin to use multiple package directories.)

Individual packages may require some additional configuration to work properly; refer to their respective README files for more information.

Multi-package tools

There is a root package.json that defines some minimal repository-level dependencies. As a convenience, running yarn install in the root will trigger a post-install script that will install dependencies for all packages.

In addition, there are some Yarn scripts defined in the root package as a convenience for running packages in a coordinated fashion:

yarn dev — starts the development servers for the Spotlight API and the Spotlight Client in a single terminal window. Be sure you have configured each of those applications with the necessary environment variables, as described in their README files, or this will not work!

yarn demo — starts the development servers for the Spotlight API and the Spotlight client in "demo mode" by supplying the necessary environment variables in the command line. (This will run your local site off of fake data fixtures rather than live data from a calculation pipeline; see the Spotlight API documentation for more information.)

yarn test - runs the tests for all packages in a single command. (The output this produces is pretty messy at the moment but it can be useful for editor integration)

Code editor integration

Your code editor may need some additional configuration to properly integrate with this monorepo setup. While not exhaustive, these are some tips we have found useful for ourselves:

Visual Studio Code

• install the ESLint plugin, and in your Workspace settings, set the ESLint Working Directories to an array of all the package directories.
• install the Jest plugin, and in your Workspace settings, set the "Jest command line" to yarn test (or one of the package-specific commands if you don't want to lint all packages; see package.json for details)

Other tools

Style and formatting rules for this repository are defined with ESLint and Prettier. Each package maintains its own configuration, and there is no central one, and thus no single command that will lint the entire repository.

Linting rules (including auto-fixing) are applied to changed files in a pre-commit hook using Husky and lint-staged. These are configured in the root package.json.

We use Github Actions for continuous integration tasks, which include lint checks as well as automated JavaScript tests where applicable.

Adding new packages

Packages in this repository are independent of each other; just create a new directory, and then run yarn init in your package directory as you normally would. (The entire repo is covered by a GPL V3 license, so make sure your package's license field conforms to that.)

There are some conventions you should follow when setting up your new package, unless you have a compelling and well-documented reason not to:

• The package name should be the same as the directory name
• yarn dev should execute the main entry point for development (e.g., starting a development server)
• yarn lint should run your static checks (linting, type-checking)
• yarn test should run your JS tests, if you have any (which you should!)