React and all the dev trimmings are a pain to set up, but they seem to be worth it in the long-run. I've tried to minimize complexity and document configuration as much as possible. I recommend configuring your editor to run Prettier on save, to lint files with eslint, and to automatically run flow to find type errors, but you can also just run these checks periodically with npm scripts.
npm run prettierPrettier formats the code automatically, so you never have to worry about it. The style might not be to your liking, but you will probably be happier if you just embrace it and not think about code formatting ever again. Write code however you want then npm run prettier to format all your code. Prettier also runs automatically as a commit hook using pretty-quick.
npm run lintAll of the style format rules have been removed from the eslint config, since formatting is all done by Prettier. The rather complicated .eslintrc config uses rules from standardjs and react and flow recommended rules in order to enforce code correctness. The rules are to avoid syntax errors and also code styles which can cause bugs, like not handling an error from a callback, or re-declaring a variable. You can configure your editor to use eslint, or lint files in the cli with npm run lint.
npm run flowFlow is a static type checker which can be a little bit of a pain to learn, but can really help with finding bugs in your code. It does a lot of work without any config - it infers types and discovers when you are trying to do something you shouldn't with an undefined variable, for example. Flow is opt-in and will only check files that start with the comment // @flow. I recommend always using this. You can add type annotations to help flow infer types. If you see a semi-colon : where it shouldn't be in normal JavaScript, it's probably a type annotation. The little effort of learning the syntax does pay off with finding bugs (if you write code as badly as me at least). If you are getting a type error but the code seems fine you can ignore the line with // $FlowFixMe on the preceding line. If you set up editor integration you will be able to see type errors and details about all your types within your editor. Run it on the whole repo with npm run flow.
flow-typed is a collection of flow type annotations for modules that don't have them. npm run flow-typed will install types for all your dependencies, updating what is already there if needed (except the files that we have manually modified). Flow automatically reads the type declarations in this folder. If you want to add type definitions for any dependencies manually, you can do so in this folder. After installing a new dependency you should run npm run flow-typed to install any type definitions needed.
Ugh, babel. Babel allows us to use JSX, it removes flow type annotations, and it allows us to use "advanced" JavaScript features like import and export instead of require(). Some of these are useful (e.g. import) because they allow static analysis, others are just syntax sugar to save repeated keystrokes. I've tried to document the babel config so you can see the additional things babel is doing. We target the last 2 major versions browsers and we don't support Internet Explorer < 11. You probably won't notice babel until it doesn't work and gives you a cryptic error. Hopefully it will just run in the background transpiling your code.
npm run storybookStorybook is pretty cool. It allows us to test out components with mocked properties. It has "hot loading" which means that if you have it open and make changes to code, the changes will appear automatically and quickly. It's really useful for seeing what your component looks like as you code it, and it works well for manual testing of components and interaction. Run npm run storybook in your terminal then open http://localhost:6006/ to see the "stories" for most of the components here. Keep it open to see the changes as you code.
npm testTests are run with Jest and use react-testing-library. We try to avoid snapshot tests and testing implementation details. If you are developing you might find it useful to continuously run tests when files change:
npm test -- --watchreact-intl is used for translations
and internationalization. Any strings should be defined at the top of each
module using
defineMessage
but unlike with the react-intl docs message descriptors are of the format [id]: message and this is transformed at build-time to the message descriptor format
using
babel-plugin-react-intl-auto.
This plugin adds the component name and path to the id, so you do not need to
worry about creating globally unique ids.
Messages for translation are in the folder messages. en.json
files are generated from the default messages in the code, and should not be
modified, but translations can be added to other files and they will not be
over-written.
To extract updated messages if you change any of the message definitions in the code:
npm run extract-messagesThis script will run on a commit hook to ensure any updated messages are always included in the commit.