Beehive

Getting set up

Grab Node 18
Clone this repo
Run ./setup-env.bash to pull down the info needed to do local GitHub auth
Run npm install to download dependencies and npm run dev to spin up the development server

You'll probably want a local instance of Sherlock running -- make local-up from inside Sherlock's repo will get you set up. You may want to dump a copy of Sherlock's database into your local one to have some data to play with.

Note

If you don't want to run a local Sherlock but you have a copy of Thelma, you can run Beehive against Sherlock's dev instance like this:
IAP_TOKEN="$(thelma auth iap --echo)" SHERLOCK_BASE_URL='https://sherlock-dev.dsp-devops.broadinstitute.org' npm run dev

Warning

If you want to do the above but against Sherlock's prod instance (careful!):
IAP_TOKEN="$(thelma auth iap --echo)" SHERLOCK_BASE_URL='https://sherlock.dsp-devops.broadinstitute.org' npm run dev

If you're using Visual Studio Code

The Tailwind plugin adds very helpful autocomplete for Tailwind's class names. This plugin is strongly recommended.

The Prettier plugin aligns the editor and pre-commit formatting behaviors. This plugin is strongly recommended.

PostCSS also has a plugin but it isn't recommended here as it unnecessarily relaxes a bunch of CSS syntax rules and ends up causing build-time syntax errors. Instead, we just ignore unknown directives in non-Tailwind CSS linting--so far that's caused far fewer errors.

Stack

TypeScript

We're just building a UI here--we already have a backend that does the business logic, Sherlock.

We're using TypeScript over JavaScript for many of the same reasons Terra UI has considered. In our case, we're starting fresh and the other tooling in this stack has really good support for it, so we have fewer downsides to using it.

NPM

We're using NPM over Yarn because NPM is the default and we don't currently have a need to Yarn's extra complexity--we can always move to it later.

React

We're using React because DSP already uses it for Terra UI and DUOS UI, and we have similar requirements for interactivity--no need to reinvent the wheel.

We use the tsx syntax since that's the most common syntax in modern resources online. Files that specifically don't include any inlined React at all can opt to use ts to help make that clear. This dovetails nicely with code-splitting hinting to Remix's compiler, resulting in session.server.ts vs clusters.tsx.

Remix

Remix is a data loading and rendering framework for React. There's two older, larger competitors, Gatsby (which I've used) and Next, but they both have gigantic feature sets far beyond what we need. Remix positions itself as a thin layer that just does your site's data loading and rendering from the server, making it super easy to bring your own actual backend--exactly what we're doing with Sherlock.

Another point in favor of Remix over Next is that Remix is essentially React Router (it's made by the same people) except it loads your data too. This makes a ton of sense for Sherlock specifically because Sherlock's data model is very hierarchical, so hierarchical routes and data-loading from Remix make for very idiomatic source code. Next plans to add similar functionality in the future, but we're building Beehive now, and Remix offers this now.

(We're glossing over a lot here, but the bottom line is that we'll probably use 90%+ of Remix versus maybe 25% of its competitors, and the competitors have more lock-in. Remix saves us from reinventing wheels that we already have from Sherlock or Identity-Aware Proxy while still letting us write, well, React.)

Tailwind

Tailwind is a library of utility CSS classes. They have an explanation of why this is a good idea but they're too humble to brag about one of their greatest features: a documentation site so thorough that we don't all need to memorize CSS or have a thousand tabs open to be able to contribute code to Beehive.

We use Tailwind as a PostCSS plugin along with a few others to help organize files (import and import-glob), improve compatibility (autoprefixer), and lower load times (cssnano); see postcss.config.js for more info. Everything in ./styles ends up in ./app/styles where Remix can grab it, but working directly with CSS in Beehive is mostly just an escape hatch for when Tailwind can't do something.

The overall architecture of the system is diagrammed here.

Documentation

Remix docs, Tailwind docs

Themes and Colors

Beehive has a theming system. This isn't just a vanity feature, it is used to vary the entire UI when affecting production resources to help avoid accidents.

To support this, use the colors defined in our Tailwind configuration (e.g. use bg-color-near-bg instead of bg-white).

If you want to add a new theme, see ./app/themes.

Icons

Lucide is set up, here's how to use it. You can apply Tailwind classes to the imported components like normal to style them.

(If you know Feather Icons, Lucide is a fork of that project with more active leadership and more icons)

broadinstitute / beehive