Many documentation updates + no throw on stderr as potential AppVeyor…

… fix

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Maximilian Stoiber
+Copyright (c) 2018 Maximilian Stoiber
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -62,7 +62,7 @@
   <dd>Unidirectional data flow allows for change logging and time travel debugging.</dd>
 
   <dt>Next generation JavaScript</dt>
-  <dd>Use template strings, object destructuring, arrow functions, JSX syntax and more, today.</dd>
+  <dd>Use template strings, object destructuring, arrow functions, JSX syntax and more.</dd>
 
   <dt>Next generation CSS</dt>
   <dd>Write composable CSS that's co-located with your components for complete modularity. Unique generated class names keep the specificity low while eliminating style clashes. Ship only the styles that are on the page for the best performance.</dd>
@@ -76,14 +76,17 @@
   <dt>Offline-first</dt>
   <dd>The next frontier in performant web apps: availability without a network connection from the instant your users load the app.</dd>
 
+  <dt>Static code analysis</dt>
+  <dd>Focus on writing new features without worrying about formatting or code quality. With the right editor setup, your code will automatically be formatted and linted as you work.</dd>
+
   <dt>SEO</dt>
   <dd>We support SEO (document head tags management) for search engines that support indexing of JavaScript content. (eg. Google)</dd>
 </dl>
 
 But wait... there's more!
 
 - _The best test setup:_ Automatically guarantee code quality and non-breaking
-  changes. (Seen a react app with 99% test coverage before?)
+  changes. (Seen a react app with 100% test coverage before?)
 - _Native web app:_ Your app's new home? The home screen of your users' phones.
 - _The fastest fonts:_ Say goodbye to vacant text.
 - _Stay fast_: Profile your app's performance from the comfort of your command
@@ -149,5 +152,5 @@ This project would not be possible without the support by these amazing folks. [
 
 ## License
 
-This project is licensed under the MIT license, Copyright (c) 2017 Maximilian
+This project is licensed under the MIT license, Copyright (c) 2018 Maximilian
 Stoiber. For more information see `LICENSE.md`.

docs/general/README.md

@@ -71,6 +71,12 @@ that's as easy as pie and the url is auto-synced to your application state!
 [react-router]: https://github.com/reactjs/react-router
 [react-router-redux]: https://github.com/reactjs/react-router-redux
 
+## Static code analysis
+
+Focus on writing new features without worrying about formatting or code quality. With the right editor setup, your code will automatically be formatted and linted as you work.
+
+Read more about linting in our [introduction](./introduction.md) and don't forget to setup your by following [our instructions](./editor.md).
+
 # Optional extras
 
 _Don't like any of these features? [Click here](remove.md)_

docs/general/commands.md

@@ -122,7 +122,7 @@ npm run start:tunnel
 ```
 
 Starts the development server and tunnels it with `ngrok`, making the website
-available on the entire world. Useful for testing on different devices in different locations!
+available worldwide. Useful for testing on different devices in different locations!
 
 ### Dependency size test
 
@@ -141,4 +141,10 @@ about the bundle size.
 npm run lint
 ```
 
-Lints your JavaScript.
+Lints your JavaScript and your CSS.
+
+```Shell
+npm run lint:eslint:fix -- .
+```
+
+Lints your code and tries to fix any errors it finds.

docs/general/editor.md

@@ -36,3 +36,5 @@ To make this happen, install both the ESLint and Prettier extensions for VSCode
   "eslint.run": "onSave"
 }
 ```
+
+Here's also a detailed video on the topic: [How to Setup VS Code + Prettier + ESLint](https://www.youtube.com/watch?v=YIvjKId9m2c)

docs/general/gotchas.md

@@ -8,6 +8,7 @@ These are some things to be aware of when using this boilerplate.
 4.  [Running tests in watch mode](#running-tests-in-watch-mode)
 5.  [When in doubt, re-install!](#when-in-doubt-re-install)
 6.  [Cleaning up Jest cache](#cleaning-up-jest-cache)
+7.  [Using short_name in Web App manifest](#using-short_name-in-web-app-manifest)
 
 ## Special images in HTML files
 

docs/general/introduction.md

@@ -2,15 +2,15 @@
 
 The [`README.md`](https://github.com/react-boilerplate/react-boilerplate#features) gives you adequate information on how to clone boilerplate files, install dependencies and launch the example app.
 
-Once you have done that, this document is intended to give you a taste of how `react-boilerplate` works. It still assumes basic knowledge of React, Redux and `react-router`. **If you're completely new to React, please refer to https://github.com/petehunt/react-howto instead!**
+Once you've done that, this document is intended to give you a taste of how `react-boilerplate` works. It still assumes basic knowledge of React, Redux and `react-router`. **If you're completely new to React, please refer to https://github.com/petehunt/react-howto instead!**
 
-This is a production-ready boilerplate, and as such optimized for browsers, not for beginners. It includes tools to help you manage performance, asynchrony, styling, everything you need to build a _real_ application. Before you get your hands dirty with the source code, we'd like you to go through a checklist, that will help you determine whether or not you're eligible to use this boilerplate. It's not because we're _holier-than-thou_, but we genuinely want to save you the frustration.
+This is a production-ready boilerplate, and as such optimized for browsers, not for beginners. It includes tools to help you manage performance, asynchrony, styling, everything you need to build a _real_ application. Before you get your hands dirty with the source code, we'd like you to go through a checklist that will help you determine whether or not you're ready to use this boilerplate. It's not because we're _holier-than-thou_, but rather because we genuinely want to save you the frustration.
 
-> Opening an issue is the fastest way to draw the attention of the team, but please make it a point to read the [docs](https://github.com/react-boilerplate/react-boilerplate/tree/master/docs) and [contribution instructions](https://github.com/react-boilerplate/react-boilerplate/blob/master/.github/CONTRIBUTING.md) before you do. The issues section is specifically used for pointing out defects and suggesting enhancements, if you have a question about one of the tools please refer to StackOverflow instead.
+Opening an issue is the fastest way to draw the attention of the team, but please make it a point to read the [docs](https://github.com/react-boilerplate/react-boilerplate/tree/master/docs) and [contribution instructions](https://github.com/react-boilerplate/react-boilerplate/blob/master/.github/CONTRIBUTING.md) before you do. The issues section is specifically used for pointing out defects and suggesting enhancements. If you have a question about one of the tools please refer to StackOverflow instead.
 
 ## Tech Stack
 
-Here's a curated list of packages that you should have knowledge of, before starting your awesome project. However, the best way to have a complete list of dependencies is to see [package.json](https://github.com/react-boilerplate/react-boilerplate/blob/master/package.json).
+Here's a curated list of packages that you should be at least familiar with before starting your awesome project. However, the best way to see a complete list of the dependencies is to check [package.json](https://github.com/react-boilerplate/react-boilerplate/blob/master/package.json).
 
 ### Core
 
@@ -30,6 +30,8 @@ Here's a curated list of packages that you should have knowledge of, before star
 ### Linting
 
 - [ ] [ESLint](http://eslint.org/)
+- [ ] [Prettier](https://prettier.io/)
+- [ ] [stylelint](https://stylelint.io/)
 
 Note that while `react-boilerplate` includes a lot of features, many of them are optional and you can find instructions in the docs on how to remove...
 
@@ -42,7 +44,7 @@ Note that while `react-boilerplate` includes a lot of features, many of them are
 
 Let's start with understanding why we have chosen our particular structure. It has been an [evolving discussion](https://github.com/react-boilerplate/react-boilerplate/issues/27), and if you have an afternoon or two we recommend you read the full thread.
 
-If not, here's the TL;DR:
+In any case, here's the TL;DR:
 
 - You will write your app in the `app` folder. This is the folder you will spend most, if not all, of your time in.
 - Configuration, generators and templates are in the `internals` folder.
@@ -52,15 +54,15 @@ If not, here's the TL;DR:
 
 We use the [container/component architecture](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0#.4rmjqneiw). `containers/` contains React components which are connected to the redux store. `components/` contains dumb React components which depend on containers for data. **Container components care about how things work, while components care about how things look.**
 
-We've found that for many applications treating single pages (e.g. the Loginpage, the Homepage etc.) as containers and their small parts (e.g. the Login form, the Navigation bar) as components works well, but there are no rigid rules. **Bend the architecture to the needs of your app, nothing is set in stone!**
+We've found that for many applications treating single pages (e.g. the LoginPage, the HomePage, etc.) as containers and their small parts (e.g. the Login form, the Navigation bar) as components works well, but there are no rigid rules. **Bend the architecture to the needs of your app, nothing is set in stone!**
 
 ### `internals/`
 
-You can call this area the "engine" of your app. Your source code cannot be executed as-is in the web browser. It needs to pass through webpack to get converted into a form that web browsers understand. While it's certainly helpful to understand what is happening here, for real world usage you won't have to mess around with this folder much.
+You can call this area the "engine" of your app. Your source code cannot be executed as-is in the web browser. It needs to pass through webpack to get converted into a version of Javascript that web browsers understand. While it's certainly helpful to understand what's happening here, for real world usage, you won't have to mess around with this folder much.
 
-- `internals/webpack`: You'll most probably use EcmaScript 6 or EcmaScript 7 to write the source code of your app. webpack takes care of making it compatible with a majority of browsers.
+- `internals/webpack`: You'll most probably use ECMAScript 6 or ECMAScript 7 to write the source code of your app. webpack takes care of making it compatible with a majority of browsers.
 
-> ([ECMAScript](http://stackoverflow.com/a/33748400/5241520) is the standard for JavaScript. Most people are still using browsers which understand ECMAScript 5. So your code must be [transpiled](https://scotch.io/tutorials/javascript-transpilers-what-they-are-why-we-need-them) into browser-understandable code. To apply the transpiler to your source code, you will use webpack. Feeling the jitters already? [Don't worry](https://hackernoon.com/how-it-feels-to-learn-javascript-in-2016-d3a717dd577f#.d2uasw2n6). Take a tea-break and then read on)
+> ([ECMAScript](http://stackoverflow.com/a/33748400/5241520) is the standard for JavaScript. Most people are still using browsers which understand ECMAScript 5. So your code must be [transpiled](https://scotch.io/tutorials/javascript-transpilers-what-they-are-why-we-need-them) into browser-understandable code. To apply the transpiler to your source code, you will use webpack. Feeling the jitters already? [Don't worry](https://hackernoon.com/how-it-feels-to-learn-javascript-in-2016-d3a717dd577f#.d2uasw2n6). Take a tea-break and then read on.)
 
 - `internals/generators`: This folder has the code to scaffold out new components, containers and routes. Read [more about scaffolding](https://github.com/react-boilerplate/react-boilerplate/tree/master/docs/general#quick-scaffolding) in the docs.
 
@@ -80,11 +82,11 @@ You can launch the example app by running `npm start`. To fully understand its i
 
 ### How does the application boot up?
 
-Like any other webpage your app starts with the [`app/index.html`](https://github.com/react-boilerplate/react-boilerplate/blob/master/app/index.html) file. React will render your application into the `div#app` .
+Like any other webpage your app starts with the [`app/index.html`](https://github.com/react-boilerplate/react-boilerplate/blob/master/app/index.html) file. React will render your application into `div#app` .
 
-But how do we include all of your react components into a single html file? That's where webpack comes into the picture. Webpack will literally pack your application into small javascript files. These files will be injected into the `index.html` as `<script>` tags.
+But how do we include all of your react components into a single HTML file? That's where webpack comes into the picture. webpack will literally pack your application into small javascript files. These files will be injected into the `index.html` as `<script>` tags.
 
-When your application is deployed on a server, browsers will load this html file. The javascript files that webpack has included will be executed by the browser, thereby booting up your react application! It's magic really!! No, not really, though it can certainly seem that way. Let's dissect this phenomenon to better know what's really going on.
+When your application is deployed on a server, browsers will load this HTML file. The Javascript files that webpack has included will be executed by the browser, thereby booting up your React application! It's magic really! No, not really, though it can certainly seem that way. Let's dissect this phenomenon to better know what's really going on.
 
 ### `app/app.js`:
 
@@ -95,13 +97,12 @@ Webpack requires an entry point to your application. Think of it as a door to yo
 `app/app.js` is one of the biggest files of the boilerplate. It contains all the global setup to make sure your app runs smoothly. Let's break its contents down:
 
 - `babel-polyfill` is imported. This enables cool stuff like generator functions, `Promise`s, etc.
+- A `history` object is created, which remembers all the browsing history for your app. This is used by the ConnectedRouter to know which pages your users visit. (Very useful for analytics, by the way.)
 - A redux `store` is instantiated.
-- A `history` object is created, which remembers all the browsing history for your app. This is used by the router to know which page your users visit. (very useful for analytics, by the way)
-- A Router is connected to Redux.
-- Hot module replacement setup via vanilla [Webpack HMR](https://webpack.js.org/guides/hot-module-replacement/) that makes all the reducers, injected sagas, components, containers, and i18n messages hot reloadable.
+- `ReactDOM.render()` not only renders the [root react component](https://github.com/react-boilerplate/react-boilerplate/blob/master/app/containers/App/index.js) called `<App />`, of your application, but it renders it with `<Provider />`, `<LanguageProvider />` and `<ConnectedRouter />`.
+- Hot module replacement is set up via vanilla [Webpack HMR](https://webpack.js.org/guides/hot-module-replacement/) that makes all the reducers, injected sagas, components, containers, and i18n messages hot reloadable.
 - i18n internationalization support setup.
 - Offline plugin support to make your app [offline-first](https://developers.google.com/web/fundamentals/getting-started/codelabs/offline/).
-- `ReactDOM.render()` not only renders the [root react component](https://github.com/react-boilerplate/react-boilerplate/blob/master/app/containers/App/index.js) called `<App />`, of your application, but it renders it with `<Provider />`, `<LanguageProvider />` and `<Router />`.
 
 * `<Provider />` connects your app with the redux `store`.
 * `<LanguageProvider />` provides language translation support to your app.
@@ -125,7 +126,7 @@ The store is created with the `createStore()` factory, which accepts three param
 In our application we are using two such middleware.
 
 1.  **Router middleware:** Keeps your routes in sync with the redux `store`.
-2.  **Redux saga:** Is used for managing _side-effects_ such as dispatching actions asynchronously or accessing browser data.
+2.  **Redux saga:** Used for managing _side-effects_ such as dispatching actions asynchronously or accessing browser data.
 
 ### Reselect
 
@@ -159,6 +160,14 @@ And this is only for **_one_** API call. In a real-world scenario, one page of y
 
 The mental model is that a saga is like a separate thread in your application that's solely responsible for side effects. `redux-saga` is a redux middleware, which means this thread can be started, paused and cancelled from the main application with normal redux actions, it has access to the full redux application state and it can dispatch redux actions as well.
 
+### Linting
+
+This boilerplate includes a complete static code analysis setup. It's composed of [ESLint](http://eslint.org/), [stylelint](https://stylelint.io/), and [Prettier](https://prettier.io/).
+
+We recommend that you install the relevant IDE extensions for each one of these tools. Once you do, every time you'll press save, all your code will be formatted and reviewed for quality automatically. (Read more at [editor.md](./editor.md).)
+
+We've also set up a git hook to automatically analyze and fix linting errors before your code is committed. If you'd like to disable it or modify its behavior, take a look at the `lint-staged` section in `package.json`.
+
 ## Example App: Behind the scenes
 
 The react-boilerplate building blocks interoperate to produce a seamless application. Let's join these pieces together.

internals/generators/language/index.js

@@ -80,10 +80,8 @@ module.exports = {
     });
     actions.push(() => {
       const cmd = 'npm run extract-intl';
-      exec(cmd, (err, result, stderr) => {
-        if (err || stderr) {
-          throw err || stderr;
-        }
+      exec(cmd, (err, result) => {
+        if (err) throw err;
         process.stdout.write(result);
       });
       return 'modify translation messages';