react-update-helper
47 |
48 |
A React set of helpers to debug and accelerate your component updates.
49 |
It works with debug and Immutable.
50 |
Goal
51 |
This react kit is a set of two high order components (HOCs) that are useful for react app development:
52 |
53 | withPureRender is the first enhancer. It helps you prevent useless component updates (even when using deep Immutable.JS objects).
54 | withDebugInfo is the second one. It allows you to check why a component updated in your browser console.
56 |
58 |
The idea combines thoughts from PureRenderMixin and from a blog post about React prop/state change debugging.
59 |
Why and when to use these helpers?
60 |
Here are a few common uses:
61 |
75 |
Still don't know if you need this? Take a look at the Usage section.
76 |
Install
77 |
It currently needs three peerDependencies.
78 |
83 |
This module is currently available only on npm.
84 |
Install now:
85 |
npm install react-update-helper --save
86 |
You are done, check the Usage section to know how to use it.
87 |
Why those peerDependencies?
88 |
React dependency is pretty obvious since this is a react plugin.
89 |
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.
90 |
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.
91 |
As for debug, it is optional and will only be required if you use withDebugInfo.
92 |
Usage
93 |
The package exposes one function and two component enhancers that you can use:
94 |
95 | shouldUpdate, the core update function with Immutable support. You may use it directly in your shouldComponentUpdate. Or you can easily switch to the enhancer approach of withPureRender.withPureRender, the easy plug-and-play enhancer HOC for any React component that will run shouldUpdate 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.
99 |
withPureRender(Component)
100 |
The easiest way to get all the goods of automatic shouldUpdate is using withPureRender.
101 |
You can use it as a normal high order component as follows:
102 |
// Use react
103 | import React from 'react';
104 |
105 | // Use withPureRender
106 | import { withPureRender } from 'react-update-helper';
107 |
108 | // Create the component
109 | class Greet extends React.Component {
110 | render() {
111 | return <div>Hello {this.props.greet}!</div>;
112 | }
113 | }
114 |
115 | // Enhance the Greet with withPureRender and export it
116 | export default withPureRender(Greet);
117 |
118 |
Or you can use it as a ES7 decorator if you support and like that way:
119 |
// Use react
120 | import React from 'react';
121 |
122 | // Use withPureRender
123 | import { withPureRender } from 'react-update-helper';
124 |
125 | // Create the enhanced component
126 | @withPureRender
127 | class Greet extends React.Component {
128 | render() {
129 | return <div>Hello {this.props.greet}!</div>;
130 | }
131 | }
132 |
133 | // Export the already enhanced Greet
134 | export default Greet;
135 |
136 |
It works with pure functional components too:
137 |
// Use react
138 | import React from 'react';
139 |
140 | // Use withPureRender
141 | import { withPureRender } from 'react-update-helper';
142 |
143 | // Create the component
144 | function Greet({ greet }) {
145 | return <div>Hello {greet}!</div>;
146 | }
147 |
148 | // Enhance the Greet with withPureRender and export it
149 | export default withPureRender(Greet);
150 |
151 |
shouldUpdate(componentContext, nextProps, nextState)
152 |
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.
153 |
Quick example of dening the greet prop value to change to falsy values while also maintaining the same value check with shouldUpdate:
154 |
// Use react
155 | import React from 'react';
156 |
157 | // Use shouldUpdate
158 | import { shouldUpdate } from 'react-update-helper';
159 |
160 | // Create the component
161 | class Greet extends React.Component {
162 |
163 | shouldComponentUpdate(nextProps, nextState) {
164 | // Ignore change to falsy value
165 | if (!!nextProps.greet) return false;
166 | // Will only return true when stuff changes, even with Immutable objects
167 | return shouldUpdate(this, nextProps, nextState);
168 | }
169 |
170 | render() {
171 | return <div>Hello {this.props.greet}!</div>;
172 | }
173 | }
174 |
175 | // Just export Greet
176 | export default Greet;
177 |
178 |
Debugging updates
179 |
Use withDebugInfo for that matter:
180 |
// Use react
181 | import React from 'react';
182 |
183 | // Use withPureRender
184 | import { withDebugInfo } from 'react-update-helper';
185 |
186 | // Create the component
187 | class Greet extends React.Component {
188 | render() {
189 | return <div>Hello {this.props.greet}!</div>;
190 | }
191 | }
192 |
193 | // Enhance the Greet with withDebugInfo and export it
194 | export default withDebugInfo(Greet);
195 |
196 |
We use debug internally to log component updates when debugging is enabled.
197 |
You can test this by enabling the namespace ReactUpdateHelper in debug.
198 |
Or you can just enable all namespaces with *.
199 |
In the browser you can do that as follows:
200 |
// Just enabling react-update-helper messages
201 | window.localStorage.debug = 'ReactUpdateHelper';
202 |
203 | // Enabling all debug-powered logs
204 | window.localStorage.debug = '*';
205 |
206 |
See more about debug in their repository page.
207 |
208 |
This custom formatter for Chrome Dev Tools makes Immutable object debugging a breeze. It works perfectly with react-update-helper!
209 |
No debug in production
210 |
As with React warnings, you should disable logs when running in a production environment.
211 |
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.
212 |
The concerns are the same as if you were building React for production usage in the first place.
213 |
If you use Webpack, here is a nice guide.
214 |
Whole documentation
215 |
See the whole docs in the docs folder of this repo or directly online.
216 |
Compatibility
217 |
Compatibility with React, Immutable and debug have been tested and should be maintained.
218 |
Though not tested, it should work with react-native since it does not mess with DOM and browser specific APIs.
219 |
It can theorically work with preact when using preact-compat since it mimics React's API and lifecycle.
220 |
Contributing
221 |
This project is welcoming contributions of any kind!
222 |
Please, before filing issues or sending PRs, read the CONTRIBUTING guide.
223 |
License
224 |
MIT
225 |
26 |
27 | 