react-update-helper
v2.0.1
Published
Precise React re-renders with debug and immutable support
Downloads
23
Readme
react-update-helper
A React set of helpers to debug and accelerate your component updates.
It works with debug and Immutable.
Goal
This react kit is a set of two high order components (HOCs) that are useful for react app development:
withPureRender
is the first enhancer. It helps you prevent useless component updates (even when using deep Immutable.JS objects).withDebugInfo
is the second one. It allows you to check why a component updated in your browser console.
The idea combines thoughts from PureRenderMixin and from a blog post about React prop/state change debugging.
Why and when to use these helpers?
Here are a few common uses:
You might want to use
withPureRender
when- You want to use Immutable objects as your props or state values.
- You use Redux with Immutable state objects
You might want to use
withDebugInfo
when:- You want to debug props and state changes.
- Pairing the component update logging with react-perf-addon to help busting performance issues.
Still don't know if you need this? Take a look at the Usage section.
Install
It currently needs three peerDependencies.
This module is currently available only on npm.
Install now:
npm install react-update-helper --save
You are done, check the Usage section to know how to use it.
Why those peerDependencies?
React dependency is pretty obvious since this is a react plugin.
Immutable is an optional choice but you might already be using it so there is no reason to duplicate the versions since this module just need the is() function of the immutable
package.
Even if you are not using Immutable on your own, most modern build systems like webpack v2
or rollup
will isolate the tiny bit of code this module need to operate.
As for debug, it is optional and will only be required if you use withDebugInfo
.
Usage
The package exposes one function and two component enhancers that you can use:
shouldUpdate
, the core update function with Immutable support. You may use it directly in yourshouldComponentUpdate
. Or you can easily switch to the enhancer approach ofwithPureRender
.withPureRender
, the easy plug-and-play enhancer HOC for any React component that will runshouldUpdate
in every update attempt for you.withDebugInfo
, the debug function you may use in development to log out a nice component change feed in the browser console.
withPureRender(Component)
The easiest way to get all the goods of automatic shouldUpdate
is using withPureRender
.
You can use it as a normal high order component as follows:
// Use react
import React from 'react';
// Use withPureRender
import { withPureRender } from 'react-update-helper';
// Create the component
class Greet extends React.Component {
render() {
return <div>Hello {this.props.greet}!</div>;
}
}
// Enhance the Greet with withPureRender and export it
export default withPureRender(Greet);
Or you can use it as a ES7 decorator if you support and like that way:
// Use react
import React from 'react';
// Use withPureRender
import { withPureRender } from 'react-update-helper';
// Create the enhanced component
@withPureRender
class Greet extends React.Component {
render() {
return <div>Hello {this.props.greet}!</div>;
}
}
// Export the already enhanced Greet
export default Greet;
It works with pure functional components too:
// Use react
import React from 'react';
// Use withPureRender
import { withPureRender } from 'react-update-helper';
// Create the component
function Greet({ greet }) {
return <div>Hello {greet}!</div>;
}
// Enhance the Greet with withPureRender and export it
export default withPureRender(Greet);
shouldUpdate(componentContext, nextProps, nextState)
You can use the shouldUpdate
function directly if you need to, like if you have more stuff to check when updating your component to improve performance.
Quick example of dening the greet prop value to change to falsy values while also maintaining the same value check with shouldUpdate
:
// Use react
import React from 'react';
// Use shouldUpdate
import { shouldUpdate } from 'react-update-helper';
// Create the component
class Greet extends React.Component {
shouldComponentUpdate(nextProps, nextState) {
// Ignore change to falsy value
if (!!nextProps.greet) return false;
// Will only return true when stuff changes, even with Immutable objects
return shouldUpdate(this, nextProps, nextState);
}
render() {
return <div>Hello {this.props.greet}!</div>;
}
}
// Just export Greet
export default Greet;
Debugging updates
Use withDebugInfo
for that matter:
// Use react
import React from 'react';
// Use withPureRender
import { withDebugInfo } from 'react-update-helper';
// Create the component
class Greet extends React.Component {
render() {
return <div>Hello {this.props.greet}!</div>;
}
}
// Enhance the Greet with withDebugInfo and export it
export default withDebugInfo(Greet);
We use debug internally to log component updates when debugging is enabled.
You can test this by enabling the namespace ReactUpdateHelper
in debug
.
Or you can just enable all namespaces with *
.
In the browser you can do that as follows:
// Just enabling react-update-helper messages
window.localStorage.debug = 'ReactUpdateHelper';
// Enabling all debug-powered logs
window.localStorage.debug = '*';
See more about debug in their repository page.
Quick Tip: When debugging Immutable objects use a custom formatter in the console
This custom formatter for Chrome Dev Tools makes Immutable
object debugging a breeze. It works perfectly with react-update-helper
!
No debug in production
As with React warnings, you should disable logs when running in a production environment.
Just make sure you are conditionally using withDebugInfo
with an environment variable of sorts (like setting NODE_ENV
to production
) and performing dead code elimination.
The concerns are the same as if you were building React for production usage in the first place.
If you use Webpack, here is a nice guide.
Whole documentation
See the whole docs in the docs
folder of this repo or directly online.
Compatibility
Compatibility with React, Immutable and debug have been tested and should be maintained.
Though not tested, it should work with react-native since it does not mess with DOM and browser specific APIs.
It can theorically work with preact when using preact-compat since it mimics React's API and lifecycle.
Contributing
This project is welcoming contributions of any kind!
Please, before filing issues or sending PRs, read the CONTRIBUTING guide.