docs: update all readme files

packages/build-config/readme.md

@@ -3,7 +3,9 @@
 hops-build-config exposes webpack configurations for Node.js, browser and webpack-dev-server.
 
 # Installation
-When you install [hops-build](https://github.com/xing/hops/tree/master/packages/build), hops-build-config will be installed as a dependency as well - so you don't necessarily have to separately install hops-build-config. If you want to use it in your app directly, install it by running
+When you install [hops-build](https://github.com/xing/hops/tree/master/packages/build), hops-build-config will be installed as a dependency as well - so you don't necessarily have to separately install hops-build-config.
+
+However iff you want to use it in your app directly (for example to extend it), install it by running
 
 ```
 npm install --save hops-build-config
@@ -21,7 +23,8 @@ Please find a list of the default configs below. If you use [hops-config](https:
 | `nodeConfig` | `String` | Path to your Webpack node/server-side rendering configuration file. Defaults to `./node_modules/hops-build-config/configs/node.js` |
 
 
-## Overwrite configs via package.json
+## Custom Webpack configuration
+Webpack configurations can be nasty to handle, therefore we recommend using [webpack-merge](https://www.npmjs.com/package/webpack-merge) if you want to extend one of the existing Webpack configurations.
 
 The following example shows how to overwrite / extend the webpack configurations:
 
@@ -86,6 +89,3 @@ PostCSS in Hops is configured to use [cssnext](http://cssnext.io/) and [CSS Modu
 | `png` `gif` `jpeg` `jpg` `webp` | Same as above, except when a file of this type is smaller than 10kb in size. In that case, it will be converted to a base64-encoded data URL and embedded inline in the referencing document |
 | `json` | Files of this type are loaded and their content is returned |
 | `tpl` | Files of this type are parsed by [_.template](https://lodash.com/docs/4.17.4#template) and their content is returned as a function. By providing such a file, you can override the default template provided by [hops-react](https://www.npmjs.com/package/hops-react) |
-
-## Custom Webpack configuration
-Webpack configurations can be nasty to handle, therefore we recommend using [webpack-merge](https://www.npmjs.com/package/webpack-merge) if you want to extend one of the existing Webpack configurations.

packages/build/readme.md

@@ -1,7 +1,7 @@
 
 # Hops Build
 
-hops-build is a wrapper around webpack and [hops-build-config](https://github.com/xing/hops/tree/master/packages/build-config) which exports a function to execute a single build.
+hops-build is a wrapper around webpack and [hops-build-config](https://github.com/xing/hops/tree/master/packages/build-config) which exports functions to execute a single build or start a `webpack-dev-server`.
 
 
 ### API
@@ -16,7 +16,7 @@ If being used without the `static` option it will run the webpack build for the
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | static | boolean | `false` | Whether to statically build app shells for all locations |
-| clean | boolean | `false` | Whether to clean the build and cache directories before starting the build |
+| clean | boolean | `true` | Whether to clean the build and cache directories before starting the build |
 
 The `callback` is being called after the build has finished and can be used to schedule further work.
 
@@ -28,7 +28,7 @@ It will take the `developConfig` with its `watchConfig` (see [hops-build-config]
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| clean | boolean | `false` | Whether to clean the build and cache directories before starting the server |
+| clean | boolean | `true` | Whether to clean the build and cache directories before starting the server |
 
 The `callback` is being called after the server has started and can be used to schedule further work.
 

packages/cli/readme.md

@@ -6,7 +6,7 @@ hops-cli provides a `hops` binary that should be installed globally.
 This binary provides different commands based on the context in which it is called.  
 If called inside a hops project it will delegate to the [hops-local-cli](https://github.com/xing/hops/tree/master/packages/local-cli) and provide the commands defined there.
 
-If called outside of a hops project it will expose just a single command `init` which can be used to initialize a new hops project based on a template (by default it will use [hops-template-default](https://github.com/xing/hops/tree/master/packages/template-default)).
+If called outside of a hops project it will expose just a single command `init` which can be used to initialize a new hops project based on a template (by default it will use [hops-template-react](https://github.com/xing/hops/tree/master/packages/template-react)).
 
 
 ## Installation
@@ -22,12 +22,12 @@ hops init my-new-hops-project [--verbose] [--npm] [--template hops-template-*]
 ```
 This will create a very basic hops example project that is ready to go.
 
-These options are additional:
+The following arguments are optional:
 * `--verbose` - to increase the verbosity of the output for debugging purposes
 * `--npm` - to force usage of `npm` instead of `yarn` even if yarn is available
 * `--template` - to specify a different template for the intial structure.
-  * available templates: `hops-template-default`
+  * available templates:
+    * [hops-template-react](https://github.com/xing/hops/tree/master/packages/template-react)
+    * [hops-template-minimal](https://github.com/xing/hops/tree/master/packages/template-minimal)
 
 Then `cd` into `my-new-hops-project` and execute `hops --help` again to see a list of supported commands. These commands are provided by [hops-local-cli](https://github.com/xing/hops/tree/master/packages/local-cli).
-
-

packages/config/readme.md

@@ -3,8 +3,9 @@
 hops-config exposes options to configure the other Hops packages and your own application. It is quite flexible and highly extensible.
 
 # Installation
-When you use any of the other hops packages, it is highly likely that you need to install `hops-config` as a peerDependency yourself.
-Please have a look at the package.json files of the other hops packages that you use or check your npm/yarn logs to see if you need to install hops-config as a peerDependency.
+
+In case you want to extend the configuration or access it from your server/browser code, you should explicitly add `hops-config` as a dependency to your project.  
+Otherwise it will be installed through the other hops packages and doesn't need to be installed directly.
 
 ```
 npm install --save hops-config
@@ -32,7 +33,7 @@ Please find a list of the default options below. They can be set in your project
 | `assets` | `Object literal` | The applications's `.js` and `.css` assets. Defaults to a getter function that returns the assets contained in the automatically generated `manifest.json` |
 | `extends` | `String` | Path to a baseline configuration (could be for example a node module or a project-specific file), allowing you join the current configuration with that baseline |
 
-Everything matching `/(config|file|dir)s?$/i` will be treated as a filesystem path (or array thereof) and resolved relative to your app's root folder. This only applies if the respective value is not an absolute path already.
+All keys matching `/(config|file|dir)s?$/i` will be treated as a filesystem path (or array thereof) and resolved relative to your app's root folder. This only applies if the respective value is not an absolute path already.
 
 ## Configure via package.json
 

packages/local-cli/readme.md

@@ -28,16 +28,16 @@ yarn add hops-local-cli
 
 hops-local-cli only lists commands that are available through other hops packages.
 
-So for example `hops build` and `hops develop` are only available if `hops-build` is installed as a dependency in your project ([`hops-template-default`](https://github.com/xing/hops/tree/master/packages/template-default) includes it by default).
+So for example `hops build` and `hops develop` are only available if `hops-build` is installed as a dependency in your project ([`hops-template-react`](https://github.com/xing/hops/tree/master/packages/template-react) includes it by default).
 
-The command `hops serve` is only available if `hops-express` is installed as a dependency in your project (also included in the default template).
+The command `hops serve` is only available if `hops-express` is installed as a dependency in your project (also included in the default react template).
 
 And the command `hops start` is only available if both `hops-build` and `hops-express` are installed as dependencies.
 
 
 ## Configuration
 
-hops-local-cli is being configured through [hops-config](https://github.com/xing/hops/tree/master/packages/config) which uses the npm config mechanism (read more at hops-config).
+hops-local-cli is being configured through `hops-config` which uses the npm config mechanism (read more at [hops-config](https://github.com/xing/hops/tree/master/packages/config)).
 
 That means that you can run `hops` commands independently and they will use the configuration from your package.json file, you cannot overwrite these values through `npm config set ...` when running hops-local-cli standalone. For that to work you need to run the hops-local-cli through your package.json `scripts` fields.
 

packages/server/readme.md

@@ -7,7 +7,7 @@ express-like interfaces to register the hops-middleware.
 It also exports a simple middleware that takes care of rewriting the paths of
 incoming http requests based on the values set in hops-config.
 
-*exports:*
+#### Exports:
 - `rewritePath(request, response, next) => void`  
 `rewritePath` is an express-style middleware that adds a trailing slash to the
 url of the incoming request.

packages/spec/readme.md

@@ -0,0 +1,4 @@
+
+# Hops Spec
+
+Hops spec contains the integration test suites and mocks and is considered a "private" package that is only used during development to very that all modules work correctly.

packages/template-react/readme.md

@@ -1,7 +1,89 @@
-# Hops Example
+# Hops Template React
 
-This folder contains an example hops project set up for development with [React](http://reactjs.com) and [React Router](https://react-router.now.sh) using the latest ECMAScript and CSS features.
+This is a small example application showing [hops](https://github.com/xing/hops) in action.
+It demonstrates how to use hops with react, redux, flow and jest.
 
-Babel, PostCSS and hops itself are configured using only `package.json`. During a build, an `index.html` is being generated using the very same React components that are being used within the browser.
+It has the following folder structure:
+```
+├── flow-typed
+├── node_modules
+├── package.json
+├── readme.md
+└── src
+    ├── app.js
+    ├── counter
+    │   ├── actions.js
+    │   ├── constants.js
+    │   ├── counterContainer.js
+    │   ├── counter.js
+    │   ├── index.js
+    │   ├── reducer.js
+    │   └── spec
+    │       ├── actions.spec.js
+    │       ├── counterContainer.spec.js
+    │       ├── counter.spec.js
+    │       ├── reducer.spec.js
+    │       └── __snapshots__
+    │           ├── counterContainer.spec.js.snap
+    │           └── counter.spec.js.snap
+    ├── home
+    │   ├── home.js
+    │   ├── index.js
+    │   ├── spec
+    │   │   ├── home.spec.js
+    │   │   └── __snapshots__
+    │   │       └── home.spec.js.snap
+    │   └── styles.css
+    └── reducers.js
+```
 
-Run this demo by `npm install`ing it and `npm start`ing it afterwards.
+This example uses `hops-react` to render in the browser or on the server via the same entry file `src/app.js`.
+
+It contains a small example of the `react-router` with two routes: `/` (home) and `/counter`.
+
+You can customize it to your needs - or use it as a reference guide when creating your own hops react project.
+
+
+## Package.json scripts
+
+### `npm start` / `yarn start`
+
+This command can be used to start a development server with hot-code reloading or to start a production server.
+
+* starting a development server: `npm start`
+* starting a production server: `npm start --production`
+
+Before you start a production server you need to build your JS bundle files.
+
+
+### `npm run build` / `yarn build`
+
+This command will generate the browser and server bundles that are required for deploying your code or running the production server through `npm start --production`.
+
+It can also be used to statically build HTML pages for all `locations` that are configured in the `"config"` section of the `package.json`.
+
+In this scenario it will iterate through the `locations` and render each location to a HTML document that will be placed in the `build/` folder.
+
+To make use of this execute `npm run build -- --static` or `yarn build --static`.
+
+
+### `npm test` / `yarn test`
+
+This command will test your code with [jest](https://facebook.github.io/jest/) a testrunner by facebook that integrates nicely with react.
+
+
+### `npm run flow` / `yarn flow`
+
+This command will run flow to typecheck your code and warn you about errors early on.
+
+
+### (`postinstall`)
+
+This script isn't really meant to be executed by the user. Instead it will run every time that you install the project or a new dependency and download the latest type definitions from [flow-typed](https://github.com/flowtype/flow-typed) for all of your dependencies.
+
+
+## Configuration
+
+Please refer to [hops-config](https://github.com/xing/hops/tree/master/packages/config) to see a list of all supported options.
+
+In this project we configure `babel` and `postcss` through the `"browsers"` field and we specify two loctions `/` and `/counter` through the `"locations"` hash.

readme.md

@@ -21,24 +21,35 @@ Hops is a modular development and build environment for universal ("isomorphic")
 Hops is designed to simplify getting started with modern frontend tooling. It streamlines [Webpack](https://webpack.js.org) and [Jest](https://facebook.github.io/jest/) configuration featuring [Babel](https://babeljs.io) and [PostCSS](http://postcss.org).
 
 
+### Quick start
+
+If you just want to get started with hops + react you can execute the following command to initialize a small example app:
+```shell
+npm install -g hops-cli
+hops init my-awesome-project
+cd my-awesome-project
+npm start
+```
+This will start hops in development mode. Visit [http://localhost:8080](http://localhost:8080) to see your app in the browser and make some changes to the code in your editor to see it live-reloading.
+
+If you want to build the JS bundles for production, run `npm run build` in your terminal and to start a Node.js server just type in `npm start --production`.
+
+
 ### Installation
 
 Besides reasonably recent versions of [Node.js](https://nodejs.org/en/) and [npm](https://www.npmjs.com), hops has no global dependencies. If you need those, we recommend using [nvm](https://github.com/creationix/nvm) or similar.
 
-If you want to go all in with hops, here's what you have to do and install to create a basic project..:
+Install the `hops-cli` globally via npm `npm install --global hops-cli` or yarn `yarn global add hops-cli`:
 
-```shell
-mkdir foo && cd foo
-npm init -y
-npm install -S hops-cli hops-config \
-  hops-react react react-dom react-helmet react-router react-router-dom \
-  hops-redux redux redux-thunk react-redux
-```
 
+### Project creation
+
+`hops init my-project` will create a directory called `my-project` and initialize an example react project inside it.
 
-### Setup
 
-After installing hops into your project, you need to set it up. This can be done within your project's `package.json` file. The relevant fields are shown below:
+### Configuration
+
+Hops is configured via the `package.json`s `"config"` field (read more about it at [hops-config](https://github.com/xing/hops/tree/master/packages/config):
 
 ```javascript
 {
@@ -66,7 +77,7 @@ Hops provides a runner that you can call from the scripts of your `package.json`
 
 For developing using hops, you can use any decent editor with up-to-date language support. Those without a favorite we recommend [Atom](https://atom.io), probably with the [linter](https://atom.io/packages/linter), [linter-eslint](https://atom.io/packages/linter-eslint) and [linter-stylelint](https://atom.io/packages/linter-stylelint) plugins.
 
-Assuming you edited your `package.json` as outlined above, you can fire up a dev server or trigger a production build like so:
+Assuming you edited your `package.json` as outlined above, you can fire up a dev or production server like so:
 
 ```shell
 npm start (--production)
@@ -79,37 +90,41 @@ If called with the `--production` flag, a production mode server is launched. Ot
 
 Hops is quite modular, its component being independently published on npm. Its main building blocks, however, rely upon each other:
 
-* [Hops CLI](https://github.com/xing/hops/tree/master/packages/cli)
+* [Hops Build](https://github.com/xing/hops/tree/master/packages/build)
+* [Hops Build Config](https://github.com/xing/hops/tree/master/packages/build-config)
+* [Hops Global CLI](https://github.com/xing/hops/tree/master/packages/cli)
 * [Hops Config](https://github.com/xing/hops/tree/master/packages/config)
+* [Hops Express](https://github.com/xing/hops/tree/master/packages/express)
 * [Hops Jest Preset](https://github.com/xing/hops/tree/master/packages/jest-preset)
+* [Hops Local CLI](https://github.com/xing/hops/tree/master/packages/local-cli)
 * [Hops React](https://github.com/xing/hops/tree/master/packages/react)
 * [Hops Redux](https://github.com/xing/hops/tree/master/packages/redux)
 
 The following additional packages are rather low-level and you'll probably never need to install and use them directly.
 
-* [Hops Transpiler](https://github.com/xing/hops/tree/master/packages/transpiler)
 * [Hops Middleware](https://github.com/xing/hops/tree/master/packages/middleware)
-* [Hops Renderer](https://github.com/xing/hops/tree/master/packages/renderer)
 * [Hops Webpack Plugin](https://github.com/xing/hops/tree/master/packages/plugin)
+* [Hops Renderer](https://github.com/xing/hops/tree/master/packages/renderer)
+* [Hops Server](https://github.com/xing/hops/tree/master/packages/server)
+* [Hops Transpiler](https://github.com/xing/hops/tree/master/packages/transpiler)
 
 
 ### Contributing
 
+Hops uses [lerna](https://github.com/lerna/lerna) and [yarn](https://yarnpkg.com/en/) for development and publishing of the packages. Therefore it is required to have `yarn` globally available.
+
 If you want to contribute to this project, create a fork of its [repository](https://github.com/xing/hops/fork) using the GitHub UI. Check out your new fork to your computer:
 
 ``` bash
 mkdir hops && cd $_
 git clone git@github.com:user/hops.git .
 ```
 
-Afterwards, you can `npm install` Hops' own dev dependencies and start the included demo project and begin developing.
+Afterwards, you can `yarn install` the required dependencies and then run `yarn bootstrap` to install the dependencies of all packages and link the packages together.
 
-``` bash
-npm install
-npm start
-```
+Using `yarn start` will execute the `start` script in the [hops-template-react](https://github.com/xing/hops/template-react) so that you can verify your changes in the browser.
 
-Whenever you run ```npm start```, the hops packages used in the demo project are being re-installed locally. When you are finished, please do go ahead and create a [pull request](https://help.github.com/articles/creating-a-pull-request/).
+When you are finished, please do go ahead and create a [pull request](https://help.github.com/articles/creating-a-pull-request/).
 
 Hops is entirely written in ECMAScript 5 and adheres to [semistandard](https://github.com/Flet/semistandard) code style. Please make sure your contribution does, too.
 
@@ -119,6 +134,7 @@ Hops is entirely written in ECMAScript 5 and adheres to [semistandard](https://g
 * [Next](https://github.com/zeit/next.js/)
 * [Gatsby](https://github.com/gatsbyjs/gatsby)
 * [Backpack](https://github.com/palmerhq/backpack)
+* [Create React App](https://github.com/facebookincubator/create-react-app)
 
 
 ### Thanks!