+
+ this will not be a part of your app shell
+
+
+```
+
+AboveTheFoldOnlyServerRender [example](https://github.com/docs-code-examples-electrode-io/electrode-progressive-beer/blob/master/client/components/home.jsx#L69-L83)
+Sample [config.js](https://github.com/electrode-io/electrode-boilerplate-universal-react-node/blob/master/config/sw-config.js)
+More on [PWA](https://developers.google.com/web/progressive-web-apps/)
diff --git a/packages/electrode-archetype-react-app/README.md b/packages/electrode-archetype-react-app/README.md
index 0aeb1b779..b114f2a4d 100644
--- a/packages/electrode-archetype-react-app/README.md
+++ b/packages/electrode-archetype-react-app/README.md
@@ -4,155 +4,215 @@
A Walmart Labs flavored React Universal App archetype.
-## tl;dr
+## Have a question? Check the [FAQ](./FAQ.md)
-#### What is this for?
+## Installation
+
+> NOTE: Generally you don't need to install these modules directly. You should start your app by using our Yeoman [generator-electrode] or check our [Electrode getting started] guide.
-This "app archetype" provides for common patterns across all app projects so that each app project can standardize on common development behavior and patterns. Its essentially pre-made patterns for build scripts.
+However, if you are manually creating your app:
-#### How do I start developing in my application project after installing?
+###### Install the two complementary modules
```bash
-# This runs both the node server and webpack (in hot mode)
-$ gulp hot
+$ npm install --save electrode-archetype-react-app
+$ npm install --save-dev electrode-archetype-react-app-dev
+```
-# Also try `dev` mode when running off battery power and you wish to maximize battery life.
-$ gulp dev
+###### Add a `gulpfile.js`
+
+The `gulpfile.js` should contain the following and be located in the root of your project
+
+```js
+require("electrode-archetype-react-app")();
```
-#### What is `hot mode`?
+## Usage
-`Hot mode` enables Hot module reloading(HMR), it is where webpack transpiles your javascript and css code and continues to watch for any changes, and, builds and loads only the code that has changed on disk. It allows you to develop without re-loading your browser page as the changes will be automagically piped in.
+The primary interface to the archetype is a list of tasks you can invoke with gulp to do your bidding.
-#### How do I run my application tests?
+To see the tasks, simply run:
```bash
-# This will run test eslint and your spec tests
-$ gulp check
+$ gulp
```
-#### How do I run my application tests without going through eslint (i.e., while I'm developing)?
+Some tasks are internal and hidden, but if you are curious, you can see them with:
```bash
-# This will run only your spec tests
-$ gulp test-dev
+$ gulp help --all
```
-#### Why can't my test and code changes get automatically run with the tests? Why do the tests take so long to start?
+To invoke a task, for example, the `dev` task, run:
```bash
-# This will start a webpack-dev-server to hot watch your code and also start a karma test browser that auto-reruns when specs or client code changes.
-$ gulp test-watch-all
+$ gulp dev
```
-#### How do I use and/or view the final build files without minifying/uglifying but also with sourcemaps?
+## AppMode
-```bash
-# This will build your code and save to disk, and then start a node server (without using webpack-dev-server).
-$ gulp dev-static
-```
+The archetype supports two app modes. The default legacy babel-register mode and the [src/lib mode](#srclib-mode).
-#### Is there anything else that might be nice for my development?
+In babel-register mode, you put your `client` and `server` code under your project's top level and your Node server requires installing babel-register to transpile your code during run time. This is not recommended due to babel-register consuming resources.
-```bash
-# This will start the node server in debug mode so that you can place breakpoints, "debugger" statements, or use `node-inspector`.
-$ gulp debug
-```
+In the [src/lib mode](#srclib-mode), you put your `client` and `server` code under the `src` directory and the `build` task will transpile them into the `lib` directory during build time.
-#### How do I view my test result in the browser?
+> In the next major release, we plan to remove the babel-register mode.
-Run either of the below commands before opening the link.
+#### babel-register mode `.babelrc`
-```
-gulp server-test
-gulp dev # (OR) (which includes `server-test`)
-gulp hot # (OR) (which includes `server-test`)
-```
-This will serve the static assets for test.html
+> Note: If you opt-in to use the src/lib mode, then this is not applicable. See [here](#srclib-babelrc) for more details.
-open [test.html]((http://localhost:3001/node_modules/electrode-archetype-react-app/config/browser_test/test.html)) to view test result.
+If you are using babel-register mode, then you need to add a `.babelrc` in your app's top level directory to extend
+[the archetype's babel configuration](config/babel/.babelrc) in order to apply the presets (ES2015, React) and the plugins like i18n. If your project needs additional Babel settings (like using stage 0 features) you can add them to this file. See the [Babel docs](https://babeljs.io/docs/usage/babelrc/) for more information.
-#### How do I generate a manifest.json and a service-worker file?
-First we need to add a `sw-config.js` file under the app's `config` folder.
-This file contains two sections:
-##### 1. Manifest
- ```
-manifest: {
- logo: "./images/icon.png",
- title: "Electrode Progressive App",
- short_name: "EPA",
- start_url: "/"
-}
- ```
- Manifest gives you control over how your web app is installed on user's home screen with `short_name, title and logo` properties. You can also specify a starting path to launch your app with `start_url` property. Manifest defines how your app appears to the user and more importantly how they can launch it.
-##### 2. Cache
-```
-cache: {
- runtimeCaching: [{
- handler: "fastest",
- urlPattern: /\/home$/
- }, {
- handler: "networkFirst",
- urlPattern: /getBeer/
- }],
- staticFileGlobs: ['dist/**/*']
+```json
+{
+ "extends": "electrode-archetype-react-app/config/babel/.babelrc"
}
```
- Seamlessly cache your static assets or run time routes or cache them together!
- Precache your static assets generated by webpack using the `staticFileGlobs` property. Or use the `runtimeCaching` property to cache specific react routes in from your `routes.jsx`.
-Once this file is added, running
-```
-gulp build
-```
-will generate a `manifest.json` file inside of `dist/js/icons-[hash]` and a service worker file `dist/sw.js`.
+## Opt-in features
-`Service Worker` file is generated during the build step and it will precache all the static resources as per the configuration in `sw-config.js`.
-Using `AboveTheFoldOnlyServerRender` you can avoid caching of certain components inside the crucial pages of your app to make your _App shell_ even lighter.
-```
-