Fingermark Cringer

Cringer

Rush

Cringer is a Rush based monorepo that contains all UI related code, from client side SDK's to the actual UI's themselves.

Developer Environment

The following tools will be required to work with Cringer (I recommend Volta if you need to manage multiple versions):

  • node (>=14.15.1)
  • pnpm (>=5.13.6)
  • @microsoft/rush (globally)

We do have an optional Vagrantfile setup to help out developers who have trouble running the system locally, if you are interested in using this please install Vagrant (you will also need to install a provider, easiest is VirtualBox).

Now run:

# Provision machine
vagrant up
# Connect to machine
vagrant ssh
# Navigate to source
cd /vagrant

If you are on Windows and see an error like this:

ERROR: EPERM: operation not permitted, unlink '/vagrant/.git/hooks/commit-msg'

You will need to delete all files in the .git/hooks directory from the Windows host.

Some developers have reported additional Windows issues related to symlinks not properly resolving, if you encounter these issues please create a ticket.

NOTE: We chose vagrant over docker for a number of reasons, the primary ones being ease of setup and the ability to run docker inside of a vagrant VM if we need it.

Getting started

Before running anything make sure you are logged into the Fingermark NPM account. Details can be found in 1Password.

To link all local dependencies via Rush run the following from the top level directory:

# Install all dependencies
rush update
# Install commands for git hooks
rush install
# Run every `build` script for each module
rush build

From here each package/library/application will maintain it's own documentation in the applications/documentation project which will contain all prevalent instructions to run locally (there should be no need for npm link as this is handled via the above commands).

NOTE: some projects will include an .env.example the README.md should include a reminder to copy this to .env however if you run into issues this is a good place to start looking.

Architecture

Rush is best used with pnpm and we have largely brought into it's custom peer resolution so installing it is unfortunately required.

By using pnpm we are able to work on all of the monorepo projects in tandem and with little additional overhead, one thing worth noting for Fingermark developers who worked with the previous (parcel and microbundle) system is that we no longer make use of the source field in the in the package.json.

This comes with the obvious drawback of no longer being able to just run the UI build while editing linked modules and actually needing to run the additional modules build process as well (Webpack does watch the node_modules/ for changes), however it does have the welcome advantage of using the additional module in it's "built" state as if it was being installed from npm.

Based on the nature of some of the projects in this monorepo we utilize a range of build tools to compile various assets, we try to maintain a level of consistency across these projects as best we can but ultimately there is a level of fragmentation that needs to be understood.

We use tsdx for packaging up all of our packages and libraries as it uses Rollup under the hood and provides a nice plugin API. We did consider running our own rollup.config.js but there were a number of resolution issues to do with pnpm, for more information see here.

Additionally tsdx is optimized to build both standard javascript SDK's as well as having React support out of the box, this makes it the ideal tool to handle our particular use case.

For applications we use a range of tools based on the requiremends of the application, some of the tools we currently use are:

  • Vitepress is used to handle all custom documentation surrounding the "Cringer" eco-system
  • Storybook is used for all of our component catalogues and uses Webpack under the hood.
  • Poi is used for all of our UI tooling, it offers a zero config abstraction over Webpack and allows us to get up and running fast

NOTE: as we use Poi to build the UI's we have to prefix all environment variables with POI_APP_.

Code quality and linters

Rush implements the notion of custom commands these coupled with the git hooks mechanism enable developers to rapidly add custom code aggregation to the development process.

For an in depth guide on how to set this up please review the Rush guide "Enabling Prettier", we have actually taken this process and extended on it considerably, as discussed in this issue.

For the official style guide please refer to this Notion document.

Eventually these documents and the Notion documents should be merged to represent one source of truth. As it stands the Notion documentation tends to handle the "intention" of any given library and these documents handle the "implementation" of each respective library.

Gotcha's

When updating the Node version in bitbucket-pipelines.yml make sure that the testing image mirrors the new Node version.