iflex-react-library

What is it?

iflex-react-library is a template to allow development and bundling of a react component library so that it can be shared as an NPM repository to your other applications or publically as an open source library. It also supports concurrent development of your app via a alias links to your library (so that you can import the library in same manner as you would when it is published) but also benefit from hot module reloading with react state preserved while making updates. Deployment of your library uses rollup (https://rollupjs.org/guide/en/) to publish library in three different formats (ESM, CommonJS ans UMD). Your local demonstration environment utilises Snowpack (https://www.snowpack.dev/) for compile speed, hot module reloading and minimal configuration and Storybook is also incorporated (and can be used optionally) to assist component documentation and showcasing.

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 spent many days and 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 created in 2021 using the most recent packaging (rollup) and tool chain technologies (Snowpack) and versions 17.x of of React.

Component Library Rollup

Using rollup under the hood, 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 together with documentation that has been 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 & Configuration

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
• Babel Babel is used during build process. The major use for exposing babel is to adopt react presets so that JSX can be indluded in files with .js extension.

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)

Installation

Create your development folder (For example my-test-react-library) for your library and extract the github report from https://github.com/Intelliflex/iflex-react-library into your development folder. This can be done from the command line by changing into your new development directory and issung the following command.

git clone https://github.com/Intelliflex/iflex-react-library .
yarn install

Preliminary Test

You can now veryify library is working by testing with the following commands

yarn storybook (This will run the storybook from /src/stories folder - you will replace these stories with your own)
yarn start     (This will run the local demonstration and testing app from /src/demo folder)

Tailoring for Your Library

Follow these steps to tailor for your library

• In package.json, Change the name field to the published name of your library (Make sure this name is available on https://www.npmjs.com/) - For example my-test-react-library
• In package.json, Change the version to 1.0.0
• In package.json, Change the description field to match the description for your library
• In package.json, Change keywords, to suit your own library
• Change the library name in path alias section of snowpack.config.js from iflex-react-library to the name of your library. You can make changes to the Sample components in src/library or when you are ready replace with your own. These changes are hot loaded with the demonstration app (/src/demo) and Storybook (/src/storybook) so that when you make changes they are instantly displayed on your browser.

That's it you are now ready to publish (ensure that you have an account on https://www.npmjs.com/ and that you are logged in via npm login - if you don't know how to do this refer to documentation on https://www.npmjs.com/).

Pushing Your Library to Github Pages

iflex-react-library provides the following scripts (inside package.json) than can be run using yarn {script name}

Script Name	Purpose
deploy-ghpages	Pushes both storybook and demonstration app to git-hub pages. The storybook is accessable via url {your gh-pages-url}/storybook
deploy-ghpages-demo	Pushes only the demonstration app to Github Pages
deploy-ghpages-storybook	Pushes only the Storybook to Github Pages

Note: Github pages uses a sub folder for each library under you user name url root. This means that references to /build/library will not work as the real reference should be /{your library name}/build/library. To counteract this the script **iflex-react-ghpages.js** is run as part of the gh-pages deployment. This will change absolute references from _/build/library_ to relative reference _build/library_

Deploying your demonstration App to other Hosting providers

yarn deploy

You may then transfer the build folder to your chosen web server. If you want to automate this then add the script associated with you target provider to the "deploy" script in package.json. Most hosting services will deploy relative to the root folder and not a sub folder (library name) like Github pages. You should change snowpack.config.js and remove the baseUrl (or make it '/')

Publishing your library

yarn publish (this will automatically run yarn build)

If your npm login details are accepted, you should now be able to see your project on https://www.npmjs.com/

Consuming your library from other Apps

Assuming that the Sample Comonents are still intact you can now consume your library in another React App. These steps will guide you through consuming library in a new App called my-test-iflex-create-library. It is assumed here that your have created and published a library called my-test-library using the steps above. If not substitute this with your own name. Create a folder for your test application (eg: my-test-consume-library) and ensure your terminal openend to this folder.

npx create-react-app .
yarn add my-test-library

Change you App.js (from /src folder) to

import React from 'react'
import { About } from 'my-test-react-library'

const App = (props) => {
  return <About />
}

export default App

Now run your Test App

yarn start

You should see the About Component from the library that you published.

Congratulations! Go forth and produce! (React component libraries that is :)

Side Note (React version and Library Upgrades)

At this time (Jan 2021) 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 your 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.