iflex-react-library

Create React Component Libraries

Motivation

If you have tried it, let's face it BUILDING REACT COMPONENT LIBRARIES IS NOT EASY!. Having used many existing templates utilising webpack or rollup I have been frustrated by various hurdles such as:-

• Library builders require outdated dependancies and break when you upgrade to latest React or other component libraries.
• Library is not published as ESM module with fallback to commonJS.
• Exports do not support CSS or SASS
• Exports do not support bundling of image and SVG imports.
• Import of modules breaks when you attempt to consume your library via an external application
• Imports break when hooks are used in your component library
• Developing your test or demonstration environment using npm link (as used by most solutions) is cumbersome and requires rebuilding package after updates, caching headaches and no support for hot loading.
• Creating a local hot linked demo / testing app requires importing of your library with relative path names such as import MyLibraryComponent from '../../lib/LayoutComponents/MyLibraryComponent.js' instead of simply import MyLibraryComponent from 'myLibraryName' as it would in a consuming application that has imported the library via NPM.

Key Features

iflex-react-library is developed in 2021 using the most recent packaging (rollup) and tool chain technologies (Snowpack) and versions 17.x of of React. At this time all packages can be updated via yarn upgrade --force to most current versions. The only exception to this presently is babel-loader which requires version 8.1.0 owing to some breaking changes that will hopefully be rectified in future versions. If you App requires React version 16.x then you can simply remove version 17 using yarn remove react react-dom and reinstalling them using yarn add -D react@16.14.0 react-dom@16.14.0. Be sure to also add these to peerDependencies object in package.json.

Component Library Rollup

Using rollup under the hood, the iflex-react-library provides component publishing in three different formats (Common JS, ESM and UMD) in a minified and obfuscated production build. After running yarn publish your library can be imported into another react application using import {yourComponentName} from 'yourLibraryName' or without curly braces for default exports.

Local Testing and Demonstration Environment

The iflex-react-library template provides local library testing and demonstration pages to be developed using the lightweight and performant Snowpack tool chain. This provides a minimal configuration, low overhead development environment with hot loading and alias mapping, allowing you to import your library in the same manner as an external application. This demonstration / testing environment may be easily published to github pages to showcase your library. Because you are not using npm link any changes made in your library are hot loaded into your application state including preseving of react state between changes.

Rapid Testing and Component Documentation using Storybook

Storybook is preconfigured to work with your component library. Simply add your stories into the stories folder and your comonents will be automatically displayed in the storybook ID together with documentation automatically assembled from comments in your component and your React PropTypes. Simply run yarn storybook to view your library components and interact with different property behaviours using the automatically created controls.

Es-Lint and TypeScript

Common es-lint addons are included for syntax and error highlighting as you develop. You can modify the .eslinttc file to configure options are add additional es-lint modules via yarn add. If you wish to add typescript then install typescript library and appropriate es-lint libraries and rename index.js entry points for your library and test environment to index.ts

Directory Structure & Config

The iflex-react-library template uses the following folders.

Directory	Contents
public	Public Assets and html (includes index.html)
dist	Distribution files for the component library that are also published to npmjs.com. These files are automatically generated when you run yarn build or yarn publish
build	These are the build files used for your local testing (using Snowpack) and storybook environment. They are not published.
src	Common folder for library components, test files and Storybook stories
src/library	Place your Library components here. You can organise folders within library in any manner that you like. This folder requires an index.js that will import and export your named Components as well as any default Component
src/demo	Place your Test Components and Pages here. You will structure this App in the same manner as you would for a React App using create-react-app (CRA) with the exception that react-scripts and other libraries installed CRA including react-scripts are not used. You will have manual control to add required packages
src/stories	Place your Stories Here. A Story file is in format ComponentName.stories.js. Refer to the sample stories and Storybook documentation for more information.
snowpack.config.js	Snowpack Configuration file. You should change the alias from iflex-react-library to your-component-name.
rollup.config.js	Rollup Configuration file. Settings in this file apply to the Library build only

Key Technologies

• Rollup
• Snowpack v3 for local demonstration and test app.
• Storybook for easy testing and documentation of components
• Sass SCSS and SASS
• Webpack & Babel Babel is used during build process. Webpack is utilised to allow alias configuration in Snowpack.config.js to be used by Storybook.

Getting Started

iflex-react-library (using rollup) will create distribution files (in dist directory) for Common JS (index.js), ESM Modules (index.modern.js) and UMD (index.umd.js)

Testing

npm start
or
yarn start

Building

npm run build
or
yarn build

Publishing

npm run publish
or
yarn publish

## Storybook

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

npm run storybook