Goodyui NPM | npm.io

`@mag/ui`

The shared React component library and Storybook for MAG-O. This repository is managed with Lerna.

Requirements

Node.js v12.x
Yarn v1.x

Integrating with your project

Install the library.

yarn add @mag/ui

Add the css bundle to your apps entry point.

import "@mag/ui/dist/main.css";

Import the components you need into your app.

import { Button } from "@mag/ui";

const MyComponent = () => {
  return (
    <div>
      ...
      <Button>Call to action</Button>
      ...
    </div>
  );
};

Testing local changes

It's likely that you will want to test changes you make in this library in conjunction with changes being made in another project. The recommended way to do this is to use a tool called yalc. While this is technically achievable through the use of yarn link or npm link, there are a bunch of gotchas associated with those commands (when working with component libraries) that are not trivial to solve.

Begin by installing yalc.

npm install -g yalc

Then run yalc publish in this packages directory, not in the monorepos root directory. Before doing this you will want to change the postpublish script in package.json to an empty string, as that command will fail when run locally.

In the directory of the project you will be using this library from run yalc add @mag/ui. Your project will now be using the "locally published" copy of @mag/ui, which will include the changes you'd made at the time of publishing. Do not commit any of the files or package.json changes that yalc makes.

With this approach you will not need to get changes to this library merged, tagged or published before you know that they work.

Scripts

Install

# in the root of the lerna repository
lerna bootstrap

Run Unit Tests

yarn test

Run Unit Tests (Watch Mode)

yarn test:watch

### Open coverage report

yarn open-coverage

Run Storybook

yarn storybook

Build Storybook

yarn build-storybook

Lint

yarn lint

Preparing a new release

When you've written tests, checked your code for best practices, reviewed your own code and had it reviewed by someone else, then you are ready to release a new version of this library. Before getting your code merged in, tag a new version using the lerna version command. This will allow you to independently version all of the packages in this monorepo.

When choosing a tag for your work, you should stick to the semver standard. This standard is used by the majority of packages on npm, and is widely understood. In brief:

<MAJOR>.<MINOR>.<PATCH>
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.

When you've selected a tag with this command it will automatically be pushed to source control. You can now merge your code into master. When code is merged into master, any versions that are unpublished will be published to MyGet via CodeBuild. The new version will now be available to install via your package manager of choice.

Should a component live here?

This library is intended to be used as a set of building blocks to build larger components across different projects. Therefore only common components and functionality should live here. If the answer to all the below questions is yes, then you should consider adding a component here:

Will it be used across multiple projects?
Is it a useful building block to make other components from?
Is there not another component that could be extended or modified for the same purpose?

Adding a new component

If you've run through the above, here's some information and best practices around adding new components to this library.

Folder structure

Components in this library live in the components folder. Every individual component should have its own folder in this directory. Each folder should contain:

The React component itself, written with TypeScript.
The CSS for the component (written using CSS Modules).
The tests for the component, written with Jest and React Testing Library.
The Storybook stories for the component.

The component should then be exported in the components/index.ts file.

Writing tests for components

As mentioned above this project uses Jest and React Testing Library to test components. Refer to the documentation for these on best practice for writing component tests. In general tests for components should be written as if a user was interacting with them, rather than testing instance methods on components as you can do with frameworks like Enzyme.

You should do your best to ensure that your component has 100% test coverage. Test coverage like be checked by Jest when running the tests, and you can see the coverage report for you latest test run by doing yarn open-coverage.

Storybook

Stories for each component should include what are thought to be the most common usages of those components. For example, if a Button component has several different styled variants then each of those should be a story, within reason. You can view the implementation of any story via the "Docs" tab in the top left hand corner of the UI.

In general the best way to test whether or not a story accurately reflects the abilities of a component is to get someone else to take a look through the Storybook UI. However below are some best practise tips for stories themselves.

Best Practice Checklist

Each component should be run through the a11y addon.
Each component should have a corresponding design asset, which should be added to each story via the design addon.
If a component has any properties passed into it, then a user should be able to edit those properties via the knobs addon on each story.
If a component has any event handlers (e.g. onClick) then these should be displayed via the actions addon.