wix-react-tools

Wix React Tools

This library provides helpful utilities and features for React components.

Notice

Current documentation (including this file) contains information matching the 3.1.x release, while the code is an advanced release candidate of 4.0.0. the changes between 3.1.x and 4.0.0 are yet only roughly documented in the Changelog.

Installation

Install wix-react-tools as a dependency in your local project.

Using npm:

npm install wix-react-tools --save

Using yarn:

yarn add wix-react-tools

@next version

To obtain the latest beta version, use the @next tag:

npm install wix-react-tools@next --save

React Component Features

A React Component Feature is a function that takes a component and returns a component with all the characteristics of the original component, plus one or more new features.

More details in React Component Features

properties feature

Connects some common component properties to the component's render output.

More details in properties feature

stylable feature

Applies a stylable stylesheet to a component, Allowing it to use the stylesheet's class and state names natively.

More details in stylable feature

disposable feature

Helps manage clean-ups according to the lifecycle of the component.

More details in disposable feature

decorateReactComponent

decorateReactComponent offers a way of applying hooks to React components in order to implement various features. These hooks temporarily monkey-patch React.createElement, React.cloneElement, and cloneElement (to be added soon) in order to customize every element created by your component. Further reading in decorateReactComponent

global ID

Produce unique ID values for react components More details in global ID

chainFunctions

Accept two function arguments. Returns a new function that when executed calls the two functions, one after the other with the same arguments, and returns void.

chainFunctions.cached

To avoid unnecessary render calls when using this utility to produce a property, the cached modifier is a memoized version, meaning calling it twice with the same arguments will produce the same result.

function chainFunctions<T extends Function>(first:T, last:T):T
function chainFunctions.cached<T extends Function>(first:T, last:T):T & {clear():void}

disposers

The Disposers class is helpful in keeping track of disposer functions and clearing them when needed.

More details in disposers

function-decor

Wrapping library for functions.

More details in function-decor

class-decor

Hooks library for ES6 classes

More details in class-decor

private-state

Privately extend any object, without inheritance or visibility concerns.

More details in private-state

configuration

Static configuration allows passing any form of data/flags to tools.

More details in config

dev mode

Constant values to use for configuring development mode on or off, and synchronizes the config's development flag with process.env.NODE_ENV.

More details in dev mode

developer documentation

how to build and test

• clone the repository
• in the cloned folder, run npm install
• run npm test to build and test the code in both nodejs and browser

how to debug (browser)

• run npm start to run a development server
• open http://localhost:8080/webtest.bundle to run live tests that will update while you change the source code

how to contribute new features

• open an issue describing the use-case for the feature.
• in that issue, explain how a user may solve the problem without the solution, describe the solution design, and the reasoning behind it.
• after agreeing on a solution design, start a branch with github reference to the issue.
• add a markdown ("readme") description of the feature in the docs, containing the feature's description, user-code level examples, and API documentation of the feature.
• write acceptance tests for the feature, including all the documented code examples. If strong typings are part of the feature's requirements, add tests in the typings-checker folder as well.
• implement the feature, add tests as needed.
• when the feature seems complete, open a pull request (PR) with github reference to the issue.

how to contribute bug fixes

The process is similar to that of new features, only the bar of explanations and documentations may be lower. start by opening an issue describing the bug.