└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # React / Redux Style Guide 2 | 3 | This is an opinionated style guide for developing applications in ES6+ with React and/or Redux. 4 | 5 | These styles are based on current best practices in the [React] and [Redux] communities, as well as real life experience 6 | with these tools in the field. It puts great focus on writing readable and maintainable code and using new JavaScript 7 | features in a responsible manner. 8 | 9 | [React]: https://facebook.github.io/react/ 10 | [Redux]: redux.js.org 11 | 12 | ## Credit 13 | 14 | Much of this style guide is based on the Redux documentation and ideas from [Dan Abramov] in particular. Furthermore, it 15 | was inspired by the [Angular Style Guide] by John Papa. 16 | 17 | [Dan Abramov]: https://github.com/gaearon 18 | [Angular Style Guide]: https://github.com/johnpapa/angular-styleguide 19 | 20 | ## Contributing 21 | 22 | This guide is opinionated. You'll probably disagree on some points. Feel free to [open an issue] or file a pull request 23 | if you think something should be rephrased or changed. Please include a detailed reasoning about why your way is better, 24 | preferably with links to other sources. I change my mind often (for the better), so please convince me. 25 | 26 | [open an issue]: https://github.com/ghengeveld/react-redux-styleguide/issues/new 27 | 28 | ## Table of Contents 29 | 30 | - [ES6 and beyond](#es6-and-beyond) 31 | - [Variables: var, let and const](#variables-var-let-and-const) 32 | - [Variables: declaration and usage](#variables-declaration-and-usage) 33 | - [Arrow functions](#arrow-functions) 34 | - [Pure functions](#pure-functions) 35 | - [Classes](#classes) 36 | - [React](#react) 37 | - [Components and containers](#components-and-containers) 38 | - [Dealing with props](#dealing-with-props) 39 | - [Redux](#redux) 40 | - [Action creators](#action-creators) 41 | - [Reducers](#reducers) 42 | - [Connecting React components](#connecting-react-components) 43 | - [Services](#services) 44 | - [Utils](#utils) 45 | 46 | ## ES6 and beyond 47 | 48 | Developers which have recently discovered the power of ES6 often feel compelled to use them on every occasion. This is 49 | not a very good idea as it can quickly lead to unreadable code. With great power comes great responsibility. 50 | 51 | ### Variables: var, let and const 52 | 53 | - Consider `var` deprecated. There is no use case for it anymore. 54 | - Use `const` by default. Immutable bindings are a good starting point. Code is easier to read and comprehend because 55 | you can be sure the variable is never re-assigned. 56 | - There's very few use cases for `let`. On many occasions you can use functions like map and reduce to avoid using it. 57 | 58 | ```js 59 | // deprecated: 60 | var foo = 'foo'; 61 | 62 | // avoid: 63 | let bar = 'bar'; 64 | 65 | // avoid: 66 | const foo = 'foo', 67 | bar = 'bar', 68 | baz = 'baz'; 69 | 70 | // recommended: 71 | const foo = 'foo'; 72 | const bar = 'bar'; 73 | const baz = 'baz'; 74 | ``` 75 | 76 | ### Variables: declaration and usage 77 | 78 | - Declare variables where you use them. 79 | - Declare each variable as a full statement. It avoids the dangling comma discussion. 80 | - Separate logical chunks of code with an empty line. 81 | 82 | ```js 83 | const foo = 'foo'; 84 | const bar = 'bar'; 85 | // use foo and bar 86 | 87 | const baz = 'baz'; 88 | // use baz 89 | 90 | const qux = 'qux'; 91 | // use qux 92 | ``` 93 | 94 | Common practice with `var` was to put all declarations at the top of their scope, even if they would only be used much 95 | further down. The reason for this is that `var` declarations are automatically hoisted to the top of their scope, so 96 | putting them there yourself makes the code more predictable. However, `let` and `const` are not hoisted. Therefore there 97 | is no reason to 'hoist' them yourself. Generally it's better to declare variables just-in-time, right before the spot 98 | where you are going to use them. This makes the code easier to follow. You won't have to go looking for usages before 99 | they are defined, because they can't be used there. It also makes it easier to extract a bunch of statements into a 100 | function, which is a great way to improve readability even more. 101 | 102 | ### Arrow functions 103 | 104 | - Consider anonymous functions deprecated. We have arrow functions for that now. 105 | - Use arrow functions only as part of a larger (named) entity, not as a stand-alone entity. 106 | - Declare functions after using them by leveraging function hoisting. 107 | 108 | ```js 109 | // deprecated 110 | function (string) { 111 | return string.toLocaleUpperCase(); 112 | } 113 | 114 | // recommended 115 | function upper(string) { 116 | return string.toLocaleUpperCase(); 117 | } 118 | 119 | // use wisely 120 | string => string.toLocaleUpperCase() 121 | 122 | // if it fits your style 123 | const upper = string => string.toLocaleUpperCase() 124 | ``` 125 | 126 | With the addition of the arrow function syntax, we have gained a very elegant and convenient way to define anonymous 127 | functions. Because they use 'lexical this', usage of `this` is more predictable. Therefore you should use arrows instead 128 | of regular anonymous functions. 129 | 130 | Unfortunately, it's tempting to forgo regular functions entirely and switch to arrows completely. Developers seem to 131 | think that with arrows, they never have to write that pesky `function` keyword again. However, a fully fledged function 132 | definition still has its merits. Arrow functions have various benefits, but also two major drawbacks: they are anonymous 133 | and they don't stand out in the code. 134 | 135 | The most important thing when writing readable code is to name things. Naming your functions is the best way to document 136 | what your code does. A well named function relieves the burden of having to read and comprehend the actual code. Another 137 | drawback of anonymous functions is that they don't encourage reuse. With arrows it's too easy to write a new function 138 | for each use case rather then reuse more generic functions. Finally, anonymous functions commonly aren't exported, which 139 | makes them hard to unit test. 140 | 141 | That being said, arrow functions certainly have their place. They are incredibly convenient as callback functions and 142 | when combined with array methods (map, reduce, forEach, filter, etc.) or other functional constructs they make for very 143 | elegant code. In the end it's up to you to find the right balance between elegance and documentation. Whenever you've 144 | written an arrow function, take a step back and consider if using a named function instead would improve readability. 145 | 146 | Like the Angular Style Guide we recommend the use of [function hoisting] in order to put your primary code at the top 147 | and implementation details at the bottom. Such code is much easier to read because it's in chronologic order and focuses 148 | on the bigger picture. If you've ever implemented this rule from the Angular Style Guide, you know this will let you 149 | grok the contents of a file much faster. 150 | 151 | You can of course assign your arrow function to a variable in order to 'name' it. Feel free to choose this approach if 152 | it fits your coding style, but consider your less functional-oriented colleagues. However, this makes regular variables 153 | and functions look extremely similar, making it harder to tell them apart. You will also lose the benefits of function 154 | hoisting. However there are also use cases where this style makes more sense, particularly if the function is a 155 | one-liner. Using a named function here would require at least three lines of code. 156 | 157 | [function hoisting]: https://github.com/johnpapa/angular-styleguide#function-declarations-to-hide-implementation-details 158 | 159 | ### Pure functions 160 | 161 | - Don't use shared mutable state or access variables from outer scope. 162 | - Don't cause any side effects by running a function. 163 | - Don't mutate any passed arguments, return a new value instead. 164 | 165 | ```js 166 | // avoid side-effects 167 | let x; 168 | function inc() { 169 | x++; 170 | } 171 | 172 | // recommended 173 | function inc(x) { 174 | return x + 1; 175 | } 176 | 177 | // avoid mutation 178 | function inc(object) { 179 | object.value++; 180 | } 181 | 182 | // recommended 183 | function inc(object) { 184 | return { ...object, value: object.value + 1 }; 185 | } 186 | ``` 187 | 188 | A sure way to reduce code complexity and enhance testability and readability is to keep your functions [pure]. This is 189 | one of the primary aspects of functional programming. It involves writing functions in a purely input-output fashion. 190 | Pure functions only work with the data they are given through their arguments and return some new data, without causing 191 | side effects. That means they cannot access outside scope and they cannot mutate their arguments. 192 | 193 | [pure]: https://en.wikipedia.org/wiki/Pure_function 194 | 195 | ### Classes 196 | 197 | - Only use classes if you have a very good reason for it. 198 | - Prefer composition over inheritance ("foo HAS a bar" instead of "foo IS a bar"). 199 | - Never inherit more than one level deep. 200 | - Never use `instanceof` checks, use duck typing instead. 201 | 202 | Classes have always been a hot topic of discussion in the JavaScript world. ES6 has introduced a new way to define 203 | classes, even though there is a growing tendency to avoid them. Programmers coming from an OOP background will 204 | appreciate them while the more functionally inclined don't like them. Developers working with React and Redux mostly 205 | prefer the functional approach, which is why using classes is discouraged. Downsides include: 206 | 207 | - Classes encourage mutation because they contain state. 208 | - Classes encourage coupling because they are used as contracts. 209 | - Classes encourage inheritance, but we want composition. 210 | - Instances can't be easily cloned without losing their type, making it hard to write pure functions. 211 | - Instance methods can't really be pure, it wouldn't make sense. 212 | - Properties are never really private. 213 | 214 | ## React 215 | 216 | ### Components and containers 217 | 218 | - Separate 'components' from 'containers'. 219 | - Prefer using a function for components, a class for containers. 220 | - Use PascalCase for component names. 221 | - Put each component in its own directory, inside index.js. 222 | - Expose components as the default export. 223 | - Expose secondary functions as named exports for unit testing. 224 | - Never export anonymous (arrow) functions. 225 | 226 | ```js 227 | // components/TodoItem/index.js 228 | export default function TodoItem(props, context) { 229 | return
  • context.onTodoClick()}>{props.label}
    • ; 230 | } 231 | 232 | // containers/TodoList/index.js 233 | export default class TodoList extends React.Component { 234 | render() { 235 | return ; 236 | } 237 | } 238 | ``` 239 | 240 | React components come in two flavors: presentation components and container components, also known as [dumb vs smart 241 | components]. We simply refer to them as 'components' and 'containers'. 242 | 243 | React v0.14 introduced a new way to write components. In the past we would write every component as a class. However, 244 | since presentation components are very lightweight, they don't need all the power that a class provides (i.e. lifecycle 245 | methods and state). 246 | 247 | The new way to write components uses a function instead of a class. Components defined that way are known as 248 | '[functional stateless components][fsc]' because they cannot have any state and they are pure functions. This means they 249 | will receive their props as an argument and must return the rendered component. It basically boils down to having only a 250 | render method, which receives the props as an argument rather than accessing it as a class property. They also receive 251 | context as a second argument. 252 | 253 | Each component or container should be inside its own directory. This reduces the clutter when components use CSS and 254 | other related files. By using `index.js` you won't have to change any import statements when you migrate from a file to 255 | a folder with the same name. If you import a folder, `index.js` is inferred. 256 | 257 | [dump vs smart components]: https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0 258 | [fsc]: https://facebook.github.io/react/blog/2015/10/07/react-v0.14.html#stateless-functional-components 259 | 260 | ### Dealing with props 261 | 262 | - Start your render method with a destructuring assignment on props and/or context. 263 | - Use the spread operator to assign multiple attributes in one go. 264 | 265 | ```js 266 | const { label, completed } = this.props; 267 | const { onTodoClick } = this.context; 268 | 269 | return 270 | ``` 271 | 272 | ## Redux 273 | 274 | ### Action creators 275 | 276 | - Group related action creators in one file. 277 | - Use [redux-promise] for asynchronous actions, or [redux-thunk] if you need more flexibility. 278 | - Expose each action creator as a named export. 279 | - Don't use a default export. 280 | 281 | ```js 282 | // actions/something.js 283 | export function doSomething() { 284 | return { 285 | type: 'DO_SOMETHING', 286 | payload: { foo: 'bar' }, 287 | meta: { baz: 'qux' } 288 | }; 289 | } 290 | ``` 291 | 292 | Action creators are functions which return an action object. An action object contains a type and optionally a payload 293 | and metadata. Action objects should follow the [Flux Standard Action] schema. 294 | 295 | We could also use the createAction helper of redux-actions, but other than enforcing FSA it doesn't do much here in 296 | terms of reducing boilerplate. In fact createAction is less readable and doesn't let us easily export named functions 297 | (exporting anonymous or arrow functions should be avoided). Note that only `type` is mandatory. 298 | 299 | ['Ducks' is a proposal][ducks] to bundle action creators with their reducers into a single file. Such a bundle is called 300 | a 'duck'. The goal is to move towards a modular application structure. So far the common practice is to group files by 301 | type rather than by feature. A [similar transition][modular angularjs] has happened in the Angular world. This style 302 | guide still follows the group-by-type pattern, but may move towards using ducks in the future. 303 | 304 | [redux-promise]: https://github.com/acdlite/redux-promise 305 | [redux-thunk]: https://github.com/gaearon/redux-thunk 306 | [Flux Standard Action]: https://github.com/acdlite/flux-standard-action 307 | [redux-actions]: https://github.com/acdlite/redux-actions 308 | [ducks]: https://github.com/erikras/ducks-modular-redux 309 | [modular angularjs]: https://medium.com/opinionated-angularjs/scalable-code-organization-in-angularjs-9f01b594bf06 310 | 311 | ### Reducers 312 | 313 | - Expose reducers as the default export. 314 | - Expose handlers as named exports for unit testing. 315 | - Use constants instead of inline strings for action types. 316 | - Always define an `initialState` variable. 317 | 318 | ```js 319 | // using redux-actions 320 | 321 | // reducers/something.js 322 | import { handleActions } from 'redux-actions'; 323 | import { Todo } from '../constants/actionTypes'; 324 | 325 | const initialState = {}; 326 | 327 | export default handleActions({ 328 | [Todo.add]: addTodo 329 | }, initialState); 330 | 331 | export function addTodo(state, action) { 332 | return { ...state, todo: action.payload.todo }; 333 | } 334 | ``` 335 | 336 | A reducer handles incoming actions. All reducers are triggered for all actions, so it's up to each reducer to decide 337 | whether or not to act on the incoming action. This is commonly done by switching on the action type. Reducers receive 338 | a current state and an action object and must return a new (updated or not) state. Their function signature is as 339 | follows: 340 | 341 | ```js 342 | (state, action) => state 343 | ``` 344 | 345 | Reducers in Redux are pure functions, which means they cannot access outside information other than the arguments they 346 | are given. It's also not allowed to mutate outside state, be it by referencing outer scope or by mutating objects which 347 | they receive as arguments. In other words they must take the data they are given and return a new state without using 348 | mutation. This can often be achieved by using the array and object spread operators. 349 | 350 | The simplest way to create a reducer is to use the handleActions method of redux-actions. This avoids having to write a 351 | switch statement and a default handler. Another benefit is that is enforces the use of FSA-compliant action objects. The 352 | final reducer should be exposed as the default export. Individual handler functions should be exposed as named exports 353 | in order to simplify unit testing. 354 | 355 | ### Connecting React components 356 | 357 | - Always use a state selector function that returns the minimal state subset you need. 358 | - Expose the connected component as default export. 359 | - Expose the unconnected component as named export for unit testing. 360 | 361 | ```js 362 | export class TodoList extends React.Component { ... } 363 | 364 | const stateSelector = ({ todos, filters }) => ({ todos, filters }); 365 | export default connect(stateSelector)(TodoList); 366 | ``` 367 | 368 | The [reselect] library works well for more complex selectors and to achieve better performance. 369 | 370 | [reselect]: https://github.com/rackt/reselect 371 | 372 | ## Services 373 | 374 | - All methods should return a promise. 375 | - Expose the entire service object as a default export. 376 | - Expose Individual service methods as named exports for unit testing. 377 | - Declare methods in alphabetical order. 378 | - Declare helper functions underneath the methods, in chronological order. 379 | - Never export anonymous (arrow) functions. 380 | 381 | ```js 382 | // services/SomethingService.js 383 | export default { 384 | getSomething 385 | }; 386 | 387 | export function getSomething() { 388 | return new Promise(resolve => resolve(helper())); 389 | } 390 | 391 | function helper() { 392 | return 'let me help you with that'; 393 | } 394 | ``` 395 | 396 | A service is where you commonly do AJAX requests to the back-end. All service methods should return a promise, even if 397 | the result is calculated synchronously. This ensures a consistent and predictable API across all services and allows 398 | changing to an asynchronous implementation later, without having to update service method calls all over the codebase. 399 | 400 | Services should expose themselves via a default export to allow consumers to import the service as a whole. The reason 401 | for this is that multiple services may expose the same generic method names, which can lead to name collisions. Services 402 | should also expose each method individually using a named export in order to aid unit testing. 403 | 404 | Service methods should be listed in alphabetical order. This keeps things tidy and avoids merge conflicts. Any helper 405 | functions should be defined underneath all exported methods and listed in the order in which they are used (i.e. 406 | chronological order, see 'Arrow functions'). Consider moving helper functions to utils and reusing them between 407 | services. 408 | 409 | ## Utils 410 | 411 | - Group related util functions under a common name. 412 | - List util functions in alphabetical order. 413 | - Expose each function as named export. 414 | - Don't use a default export. 415 | - Util functions must be pure. 416 | - Util functions should be reusable, but have a single purpose. 417 | 418 | ```js 419 | // utils/serialization.js 420 | export function upper(string) { 421 | return string.toLocaleUpperCase(); 422 | } 423 | ``` 424 | 425 | Utils is a collection of various supporting functions. It is a good idea to extract a function to a util when you are 426 | doing the same thing in multiple places throughout the codebase. If you do are not using the function in several files, 427 | it probably should not be a util function. 428 | 429 | Exported functions should be defined in alphabetical order to make them easy to locate and avoid merge issues. Each 430 | function should be exposed using a named export. A utils file should not expose a default export, as it does not 431 | represent an entity as a whole but is merely a bag of related functions. 432 | 433 | Utility functions may never keep internal state, nor can they use services. They should be pure functions. Each exported 434 | function should be suitable for multiple uses (i.e. generic enough to be reused), but they should have a single well 435 | defined purpose (i.e. do one thing, and do it well). 436 | --------------------------------------------------------------------------------