@dossier/mithra-ui

Mithra UI

React component library for the Dossier design system

• Documentation
• Bitbucket

Getting started

Set up local development environment:

1. Run yarn
2. Run yarn run build-lib to generate the version file.
3. Run yarn start to start the dev server.

The local dev server gives you a live-reloaded version of the mithra documentation, that you can use to test components while working on them.

If you don't use yarn, you can use npm instead, or install Yarn 1.

Other useful commands:

• yarn run build-lib
• yarn run build-doc
• yarn run import-icons

Technology stack

• create-react-app
• SCSS
• TypeScript

Development and branches

Development happens in feature branches, for example feature/MU-123-add-context-menu. These are merged by pull request to release branches, for example release/v2.next. There is one combined development/release branch for each major version. Later version branches include changes from earlier versions; for example, v1 is included (merged) into v2, but not vice versa.

When making changes that affect users of the library, please add a concise comment about the change at the top of the CHANGELOG file.

To determine which release branch a feature should be merged to, use SemVer (breaking changes → next major, non-breaking changes → next minor or patch).

Code style

We use automatic code formatting with Prettier. You should set this up with your editor when contributing.

VS Code: The project already contains configuration that makes the editor format on save, but you must install the Prettier extension. This will be prompted when you open the project.

IntelliJ: Install the Prettier extension, and choose the node_modules Prettier in its settings.

Releasing packages

Don't follow the steps below unless you know what you're doing.

Steps to release on npm:

• Checkout the correct release branch with your changes.
• Run the appropriate npm version major|minor|patch to update package.json and create a tagged commit.
• Push the commit to bitbucket (git push).
• Push the resulting git tag to bitbucket (git push --tags).
• This triggers the npm publish pipeline, which is irreversible. It also rebuilds and deploys the docs site.

Importing icons from Figma

1. Select the icons in Figma and batch export everything as svg.
2. Create a folder in the project root called ./iconBuildSrc
3. Extract the downloaded zip into the iconBuildSrc
4. Run yarn run import-icons
5. Modify src/lib/assets/icons/icons/index.js as needed if the categories have changed
6. Voilà. Delicious icons.

Snapshot testing

The image snapshot tests take screenshots of test layouts using puppeteer and jest. The images are then compared with previous snapshots using jest-image-snapshot. This alerts us to unintended visual changes to components. If a test fails, an image file will be created, with a visual diff of the change. These tests also run automatically in a bitbucket pipeline for all pull requests. If they fail, you can download the diff images for the failed tests in an artifact from bitbucket.

To run and/or update the tests locally, you must have Docker on your system. The snapshot tests need Docker in order to render exactly the same, regardless of different developer systems and CI.

Running the tests in the docker container

Before running the tests, be sure you have a dev server running locally. Docker must also be installed.

# Run dev server on your local machine
yarn start

Then you can run the snapshot tests in a container. The following command starts a container and executes all the snapshot tests (against your dev server). The first time you run this command it will spend some time downloading the image and installing node_modules.

# Run tests in the container
yarn test:docker-run

# Or, using jest interactive mode
yarn test:docker-run-interactive

Then if there are any failures, you can see the diffs in __tests__/__image_snapshots__/__diff_output__.

You can update the snapshots by running following command, or through the interactive jest runner terminal ui.

# Run tests in the container
yarn test:docker-run -u

To shut down the container and Docker resources after testing, run:

yarn test:docker-cleanup

About the Docker test environment

Both the local test environment and the bitbucket pipeline use the official puppeteer image. The local environment is managed by Docker compose (see docker-compose.yml).