@mindprint-learning/design v1.2.3

MindPrint Learning Design

About

This project uses Storybook to create common UI components across our projects and apps.

We also use Chromatic to view visual changes to the component library, leave comments, and approve changes

Learning Storybook

1. Read our introductory tutorial over at Storybook tutorials.
2. Learn how to transform your component libraries into design systems in our Design Systems for Developers tutorial.
3. See our official documentation at Storybook.

Chromatic

https://www.chromatic.com/builds?appId=61cb91b07929a8004aedeecd

Development

Adding Components

1. Create a feature branch (e.g., lukes-new-buttons)
2. Run yarn storybook and start coding.
3. When you're ready, create a pull request against main in Github
4. Opening a pull request will trigger a build in the Chromatic Project and add Chromatic-specific checks to the PR.

5. Go to the Storybook Publish check and click on "details":

   

6. This will open the Storybook build reflecting your changes:

   

7. For each component you added or modified, copy the url in the browser and paste it in the comments section of your PR:

   

8. Solicit a review in Chromatic:

   

9. Review approvals or denials in Chromatic will be shown in the PR checks:

   

10. Once all checks and reviews are passed, merge to main

Publishing the Library

Official Release

A merge to main triggers a release of the library on npm:

https://www.npmjs.com/package/@mindprint-learning/design

This is considered an official release and any projects using "@mindprint-learning/design": "latest" will be implicitly updated.

Dev release

Running yarn release will create a version of the library on npm as well. The version will look like this: @mindprint-learning/design@0.1.17--canary.6f5ff32.0

You can use this to troubleshoot, etc., but the above PR/Approval process above should be the standard procedure for making changes to this library.

Local Development

You may want to build a Storybook library component while also seeing how it looks like in an app (e.g., building a card component that is used in strategies.mindprintlearning.com). The procedure below enables efficient development in this context:

• Put this project as a sibling next to the consuming project
• cd into /design
• Run yarn link
• cd into ../<project>
• Run yarn link "@mindprint-learning/design"
• After making changes to a component, in /design run yarn build. A project (using create-react-app) will reload automatically with the changes.

• Note: It is common with npm/yarn link to encounter an invalid hook error. To fix this error, try the following:

  • cd into /<project>/node_modules/react
  • yarn link
  • cd into /design
  • yarn link react
  • see more discussion here
  • This is an option that may work as well. In your consuming project project.json, replace react and react-dom with:

  "react": "link:../design/node_modules/react",
  "react-dom": "link:../design/node_modules/react-dom",

  • See Yarn Link for more details

Resources

Template copied from react-component-library

Atomic Design resources:

• Adobe react-spectrum

TEMPLATE README

Below is the readme for the template this project was generated from:

see https://github.com/HarveyD/react-component-library

React Component Library

This project skeleton was created to help people get started with creating their own React component library using:

• Rollup
• Sass
• TypeScript

It also features:

• Storybook to help you create and show off your components
• Jest and React Testing Library enabling testing of the components

Read my blog post about why and how I created this project skeleton ▸

Check out this CodeSandbox to see the component library in action ▸

Development

Testing

yarn test

Building

yarn build

Storybook

To run a live-reload Storybook server on your local machine:

yarn storybook

To export your Storybook as static files:

yarn storybook:export

You can then serve the files under storybook-static using S3, GitHub pages, Express etc. I've hosted this library at: https://www.harveydelaney.com/react-component-library

Generating New Components

I've included a handy NodeJS util file under util called create-component.js. Instead of copy pasting components to create a new component, you can instead run this command to generate all the files you need to start building out a new component. To use it:

yarn generate YourComponentName

This will generate:

/src
  /YourComponentName
    YourComponentName.tsx
    YourComponentName.stories.tsx
    YourComponentName.test.tsx
    YourComponentName.types.ts
    YourComponentName.scss

The default templates for each file can be modified under util/templates.

Don't forget to add the component to your index.ts exports if you want the library to export the component!

Installing Component Library Locally

Let's say you have another project (test-app) on your machine that you want to try installing the component library into without having to first publish the component library. In the test-app directory, you can run:

npm i --save ../react-component-library

which will install the local component library as a dependency in test-app. It'll then appear as a dependency in package.json like:

  ...
  "dependencies": {
    ...
    "react-component-library": "file:../react-component-library",
    ...
  },
  ...

Your components can then be imported and used in that project.

NOTE: After installing the component library locally, you may run into:

Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:

You might have mismatching versions of React and the renderer (such as React DOM)
You might be breaking the Rules of Hooks
You might have more than one copy of React in the same app See for tips about how to debug and fix this problem.

This is the most commonly encountered problem people face when installing the library locally. This is most likely due to the third reason: You might have more than one copy of React in the app.

Normally when a library is published, dev dependencies are excluded. However, when the library is symlinked, all local dev depdendencies are persisted in the libraries node_modules (includes React). Your bundler may see two versions of React, one in the consuming app and one in the symlinked library. The solution is to have the component library use the React version in the consuming app. So from your component library folder, run:

npm link ../test-app/node_modules/react

OR, if you are using Webpack in app you can follow this GitHub comment.

Read more about this issue here.

Publishing

Hosting via NPM

First, make sure you have an NPM account and are logged into NPM using the npm login command.

Then update the name field in package.json to reflect your NPM package name in your private or public NPM registry. Then run:

npm publish

The "prepublishOnly": "npm run build" script in package.json will execute before publish occurs, ensuring the build/ directory and the compiled component library exist.

Hosting via GitHub

I recommend you host the component library using NPM. However, if you don't want to use NPM, you can use GitHub to host it instead.

You'll need to remove build/ from .gitignore, build the component library (npm run build), add, commit and push the contents of build. See this branch for an example.

You can then install your library into other projects by running:

npm i --save git+https://github.com/HarveyD/react-component-library.git#branch-name

OR

npm i --save github:harveyd/react-component-library#branch-name

Usage

Let's say you created a public NPM package called harvey-component-library with the TestComponent component created in this repository.

Usage of the component (after the library installed as a dependency into another project) will be:

import React from "react";
import { TestComponent } from "harvey-component-library";

const App = () => (
  <div className="app-container">
    <h1>Hello I'm consuming the component library</h1>
    <TestComponent theme="primary" />
  </div>
);

export default App;

Check out this Code Sandbox for a live example.

Using Component Library SASS Variables

I've found that it's helpful to export SASS variables to projects consuming the library. As such, I've added the rollup-plugin-copy NPM package and used it to copy the src/typography.scss and variables.scss into the build directory as part of the Rollup bundle process. This allows you to use these variables in your projects consuming the component library.

For example, let's say you installed harvey-component-library into your project. To use the exported variables/mixins, in a SASS file you would do the following:

@import '~harvey-component-library/build/typography';

.example-container {
    @include heading;

    color: $harvey-white;
}

Additional Help

Dark Mode

The example component TestComponent respects the user's dark mode operating system preferences and renders the component in the appropriate theme.

This is achieved by using the media query: @media (prefers-color-scheme: dark) in combination with CSS variables. The colours that change depending on dark mode preference can be found in src/variables.scss. Example usage of these variables can be found within src/TestComponent/TestComponent.scss.

Read https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme for more details.

Using Alternatives to Sass

Less or Stylus

The Rollup plugin rollup-plugin-postcss supports Sass, Less and Stylus:

• For Stylus, install stylus: yarn add stylus --dev
• For Less, install less: yarn add less --dev

You can then remove node-sass from your dependencies.

CSS Modules

If you want to use CSS Modules, update postcss in rollup-config.js to:

postcss({
  modules: true
})

Styled Components

If you want to use styled-components, the changes required are a bit more involved. As such, I've created a branch where I've got styled-components working in this component library, check it out here.

Component Code Splitting

Code splitting of your components is not supported by default.

Read this section of my blog post to find out how and why you would enable code splitting of your components. In summary, code splitting enables users to import components in isolation like:

import TestComponent from 'harvey-component-library/build/TestComponent';

This can reduce the bundle size for projects using older (CJS) module formats.

You can check out this branch or this commit to see what changes are neccesary to implement it.

Please note, there's an issue with code splitting and using rollup-plugin-postcss. I recommend using rollup-plugin-sass instead alongside code splitting.

Supporting Image Imports

Add the following library to your component library @rollup/plugin-image:

npm i -D @rollup/plugin-image

Then add it to rollup-config.js:

...
plugins:[
  ...,
  image(),
  ...
]
...

You can then import and render images in your components like:

import logo from "./rollup.png";

export const ImageComponent = () => (
  <div>
    <img src={logo} />
  </div>
);

Supporting JSON Imports

Add the following library to your component library @rollup/plugin-json:

npm i -D @rollup/plugin-json

Then add it to rollup-config.js:

...
plugins:[
  ...,
  json(),
  ...
]
...

You can then import and use JSON as ES6 Modules:

import data from "./some-data.json";

export const JsonDataComponent = () => <div>{data.description}</div>;

Checkout the official Rollup plugin list for additional helpful plugins.