React Utils

A collection of generic ReactJS configurations, components, and utilities.

Forked from Topcoder React Utils.

Content

• Installation
• Reference
  • Standard Configurations
  • Components
  • NodeJS Scripts
  • Utilities
• Development
  • Local Testing of Library Updates within a Host Project
  • Library Releases to NPM
• License

Installation

Install the package as

$ npm install --save @dr.pogodin/react-utils
$ ./node_modules/.bin/react-utils-setup

Then import the global stylesheet into the root ReactJS component of your app:

/* eslint-disable global-require */
if (process.env.NODE_ENV === 'production') {
  require('@dr.pogodin/react-utils/prod-styles');
} else {
  require('@dr.pogodin/react-utils/dev-styles');
}
/* eslint-enable global-require */

To upgrade this library to the latest version just execute again

$ ./node_modules/.bin/react-utils-setup

Reference

Standard Configurations

• Babel
• ESLint
• Jest
• Stylelint
• Webpack

Components

• <Avatar> – The standard component for user avatars.
• <Button> – Handles buttons and button-like links (components that look like regular buttons, but behave as links) in the same uniform manner.
• <CodeSplit> – Code splitting component.
• <GlobalStateProvider> – Alias for <GlobalStateProvider> from @dr.pogodin/react-global-state.
• <Link> and <NavLink> – Auxiliary wrappers around the React Router's components of the same names. Allow to handle external and internal links in the same uniform manner.
• <Modal> – Themeable modal component.
• <PageLayout> – Simple and configurable page layout.
• <ScalableRect> – Container that keeps the specified aspect ratio regardless the width you set.
• <Throbber> – Simple activity indicator (three bouncing circles).
• <Tooltip> – Tooltip component.

NodeJS Scripts

• react-utils-build – The script for Babel, and Webpack build of the library and derived apps. Can be used to work around issues with npm link command for the library development within dependant projects.
• react-utils-setup – The script for library installation and upgrades.

Utilities

• _ – Alias of lodash (JS utilities).
• api – Alias of axios (API / HTTP client).
• client – Client-side initialization code.
• config – Isomorphic app config.
• Global Styles – Global SCSS styles necessary for a generic application.
• hooks – Different React hooks.
• isomorphy – Collection of helpers to deal with isomorphic aspects of the code.
• JU – jest utilities.
• PT – Alias of prop-types.
• React Themes – Aliases for dr.pogodin/react-themes. UI styles for React components with theme composition.
• SCSS Mixins – Collection of useful style mixins;
• server – Easy creation and launch of web-server with standard configuration, that serves a ReactJS application with or without server-side rendering, supports development tools (Hop Module Reloading), and can be further configured for the needs of specific projects.
• time – Alias of moment + related utils. Everything needed to deal with date & times.
• url – URL utils.
• webpack – Various utils related to the Webpack bundling process.

Development

Whenever you are to do any changes in the library, keep in mind the following:

• Different projects rely on this library, the tooling it provides should be as generic and flexible as possible. When you change existing components, do your best to keep backward compatibility of the updated components, any changes that demand updates in the projects relying on the library, must be documented in the changelog.

• Rely on unit tests to verify your changes, and prevent regression. Update existing unit tests to keep up with your changes, and add new unit tests when necessary.

• For the final testing of your updates within a host project relying on this lib, see the next section.

• The library use semantic versioning. In case your changes demand any changes in the project relying on the library, you should release it as a minor library update (more severe comparing to patch update). Consider to use a new branch, called after the minor version, and to not merge your changes into the main develop / master branches until everybody is prepared for that.

Local Testing of Library Updates within a Host Project

To locally test how your library updates work within a host project relying on the lib (without releasing them to NPM), use npm link to link local copy of the lib into the host project, then run npm run build:dev:watch in the library root to automatically re-build the lib when you change it, and use the host project to see the final effect of changes you make.

Library Releases to NPM

Continious Integration and Delivery (CI/CD) is set up for this repository with CircleCI 2.0. Commits to all branches trigger testing of the code with $ npm test (it runs linters and unit tests), and also build the library. CI/CD flow is interrupted in case of any problems.

To release updated library version to NPM do the following:

• Bump library version in package.json and package-lock.json by $ npm version UPDATE_TYPE --no-git-tag command, where UPDATE_TYPE should be one of patch / minor / major to update current version x.y.z to x.y.(z+1) / x.(y+1).0 / (x+1).0.0. The --no-git-tag flag prevents automatic creation of the Git tag with the same name as the version.

• Tag the commit to be released with the git tag like v0.1.2, where 0.1.2 is the new version set in the previous step.

• Commit the tag to GitHub repository.

License

React Utils are MIT Licensed.