devtools/docs/contributor/frontend/react-guidelines.md

   1
   2 # Guidelines for Writing React
   3
   4 These are soft rules for writing react devtools code. Try to stick to
   5 these for consistency, and if you disagree, file a bug to change these
   6 docs and we can talk about it.
   7
   8 **Please also read** the [coding
   9  standards](https://wiki.mozilla.org/DevTools/CodingStandards#React_.26_Redux)
  10 for react and redux code. The guidelines here are more general
  11 patterns not specific to code style.
  12
  13 ## Why no JSX?
  14
  15 You probably already noticed we don't use JSX. The answer isn't
  16 complicated: we don't build our JS code, and we write directly for our
  17 JS engine, SpiderMonkey. It already supports much of ES6, but it does
  18 not support JSX (which is not a standard).
  19
  20 This may change if we ever adopt a build step. Even so, the author is
  21 not convinced that JSX helps enough to warrant all the syntax. It is
  22 clearer sometimes, but it can be noisy switching between JSX and JS a
  23 lot.
  24
  25 It's not as bad as you may think! If you are used to JSX it may be an
  26 adjustment, but you won't miss it too much.
  27
  28 ## One component per file
  29
  30 Try to only put one component in a file. This helps avoid large files
  31 full of components, but it's also technically required for how we wrap
  32 components with factories. See the next rule.
  33
  34 It also makes it easier to write tests because you might not export
  35 some components, so tests can't access them.
  36
  37 You can include small helper components in the same file if you really
  38 want to, but note that they won't be directly tested and you will have
  39 to use `React.createElement` or immediately wrap them in factories to
  40 use them.
  41
  42 ## Export the component directly and create factory on import
  43
  44 Modules are the way components interact. Ideally every component lives
  45 in a separate file and they require whatever they need. This allows
  46 tests to access all components and use module boundaries to wrap
  47 components.
  48
  49 For example, we don't use JSX, so we need to create factories for
  50 components to use them as functions. A simple way to do this is on
  51 import:
  52
  53 ```js
  54 const Thing1 = React.createFactory(require('./thing1'));
  55 const Thing2 = React.createFactory(require('./thing2'));
  56 ```
  57
  58 It adds a little noise, but then you can do `Thing1({ ... })` instead
  59 of `React.createElement(Thing1, { ... })`. Definitely worth it.
  60
  61 Additionally, make sure to export the component class directly:
  62
  63 ```js
  64 const Thing1 = React.createClass({ ... });
  65 module.exports = Thing1;
  66 ```
  67
  68 Do not export `{ Thing1 }` or anything like that. This is required for
  69 the factory wrapping as well as hot reloading.
  70
  71 ## More to Come
  72
  73 This is just a start. We will add more to this document.