tunstall-ui-library v1.7.1
React Component Library
This project skeleton was created to help people get started with creating their own React component library using:
- Rollup
- TypeScript
Sass(This dependency has been removed, see Using CSS Preprocessors on how to support it)
It also features:
- Storybook to help you create and show off your components
- Jest and React Testing Library enabling testing of the components
Development
npm run storybook
Testing
npm run test
Building
npm run build
Storybook
To run a live-reload Storybook server on your local machine:
npm run storybook
To export your Storybook as static files:
npm run storybook:export
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:
npm run generate YourComponentName
This will generate:
/src
/YourComponentName
YourComponentName.tsx
YourComponentName.stories.tsx
YourComponentName.test.tsx
YourComponentName.types.ts
YourComponentName.css
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.
Stylesheet
First, you'll need to import the index.css
CSS file distributed by the package. This should be done at the root of your project (in index.js
or App.tsx
of your React app) and will look like:
export default App;
See: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties for more information about CSS Variables.
## 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/index.css`](src/index.css). Example usage of these variables can be found within [`src/TestComponent/TestComponent.css`](src/TestComponent/TestComponent.css).
Read https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme for more details.
### Using CSS Preprocessors
The Rollup plugin [`rollup-plugin-postcss`](https://github.com/egoist/rollup-plugin-postcss) supports Sass, Less and Stylus:
- For Sass, install less: `yarn add node-sass --dev`
- For Stylus, install stylus: `yarn add stylus --dev`
- For Less, install less: `yarn add less --dev`
#### CSS Modules
If you want to use CSS Modules, update `postcss` in `rollup-config.js` to:
postcss({ modules: true })
### Supporting Image Imports
Add the following library to your component library [@rollup/plugin-image](https://github.com/rollup/plugins/tree/master/packages/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:
```tsx
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.