solstice-web/README.md

React Slingshot!

React Slingshot is a comprehensive starter kit for rapid application development using React. It offers a rich development experience including:

Tech	Description	Learn More
React	Fast, composable client-side components.	Pluralsight Course
Redux	Enforces unidirectional data flows and immutable, hot reloadable store. Supports time-travel debugging. Lean alternative to Facebook's Flux.	Tutorial
Babel	Compiles ES6 to ES5. Enjoy the new version of JavaScript today.	ES6 REPL, ES6 vs ES5, ES6 Katas, Pluralsight course
Webpack	Bundles npm packages and our JS into a single file. Includes hot reloading via react-transform-hmr.	Quick Webpack How-to Pluralsight Course
Browsersync	Lightweight development HTTP server that supports synchronized testing and debugging on multiple devices.	Intro vid
Mocha	Automated tests with Chai for assertions and Cheerio for DOM testing without a browser using Node.	Pluralsight Course
TrackJS	JavaScript error tracking.	Free trial
ESLint	Lint JS. Reports syntax and style issues. Using eslint-plugin-react for additional React specific linting rules.
SASS	Compiled CSS styles with variables, functions, and more.	Pluralsight Course
Editor Config	Enforce consistent editor settings (spaces vs tabs, etc).	IDE Plugins
npm Scripts	Glues all this together in a handy automated build.	Pluralsight course, Why not Gulp?

The starter kit includes a working example app that puts all of the above to use.

Get Started

1. Initial Machine Setup. First time running the starter kit? Then complete the Initial Machine Setup.
2. Clone the project. git clone https://github.com/coryhouse/react-slingshot.git.
3. Install Node packages. npm install
4. Run the example app. npm start -s
   This will run the automated build process, start up a webserver, and open the application in your default browser. When doing development with this kit, you'll want to keep the command line open at all times so that your code is rebuilt and tests run automatically every time you hit save. Note: The -s flag is optional. It enables silent mode which suppresses unnecessary messages during the build.
5. Review the example app. This starter kit includes a working example app that calculates fuel savings. Note how all source code is placed under /src. Tests are placed alongside the file under test. The final built app is placed under /dist. These are the files you run in production.
6. Delete the example app files. Once you're comfortable with how the example app works, you can delete those files and begin creating your own app.

##Initial Machine Setup

1. Install Node 4.0.0 or greater
2. Install Git.
3. Install React developer tools and Redux Dev Tools in Chrome. (Optional, but helpful. The latter offers time-travel debugging.)
4. On a Mac? You're all set. If you're on Linux or Windows, complete the steps for your OS below.

On Linux:

• Run this to increase the limit on the number of files Linux will watch. Here's why.
  echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

On Windows:

• Install Python 2.7. Some node modules may rely on node-gyp, which requires Python on Windows.
• Install C++ Compiler. Browser-sync requires a C++ compiler on Windows. Visual Studio Express comes bundled with a free C++ compiler. Or, if you already have Visual Studio installed: Open Visual Studio and go to File -> New -> Project -> Visual C++ -> Install Visual C++ Tools for Windows Desktop. The C++ compiler is used to compile browser-sync (and perhaps other Node modules).

##FAQ ###Why does this exist? This starter kit implements best practices like testing, minification, bundling, and so on. It codifies a long list of decisions that you no longer have to make to get rolling. It saves you from the long, painful process of wiring it all together into an automated dev environment and build process. It's also useful as inspiration for ideas you might want to integrate into your current development environment or build process.

###What do the scripts in package.json do? Unfortunately, scripts in package.json can't be commented inline because the JSON spec doesn't support comments, so I'm providing info on what each script in package.json does here.

Script	Description
prestart	Runs automatically before start. Calls remove-dist script which deletes the dist folder. This helps remind you to run the build script before committing since the dist folder will be deleted if you don't. ;)
start	Runs tests, lints, starts dev webserver, and opens the app in your default browser.
lint:tools	Runs ESLint on build related JS files. (eslint-loader lints src files via webpack when npm start is run)
clean-dist	Removes everything from the dist folder.
remove-dist	Deletes the dist folder.
create-dist	Creates the dist folder and the necessary subfolders.
build:html	Adds trackJS tracking script and copies to /dist.
prebuild	Runs automatically before build script (due to naming convention). Cleans dist folder, builds html, and builds sass.
build	Bundles all JavaScript using webpack and writes it to /dist.
test	Runs tests (files ending in .spec.js) using Mocha and outputs results to the command line. Watches all files so tests are re-run upon save.

###Can you explain the file structure?

.
├── .babelrc                  # Configures Babel
├── .editorconfig             # Configures editor rules
├── .eslintrc                 # Configures ESLint
├── .gitignore                # Tells git which files to ignore
├── README.md                 # This file.
├── dist                      # Folder where the build script places the built app. Use this in prod.
├── package.json              # Package configuration. The list of 3rd party libraries and utilities
├── src                       # Source code
│   ├── actions               # Flux/Redux actions. List of distinct actions that can occur in the app.  
│   ├── businessLogic         # Plain old JS objects (POJOs). Pure logic. No framework specific code here.
│   ├── components            # React components
│   ├── constants             # Application constants including constants for Redux
│   ├── containers            # App container for Redux
│   ├── favicon.ico           # favicon to keep your browser from throwing a 404 during dev. Not actually used in prod build.
│   ├── index.html            # Start page 
│   ├── index.js              # Entry point for your app
│   ├── reducers              # Redux reducers. Your state is altered here based on actions
│   ├── store                 # Redux store configuration
│   └── styles                # CSS Styles, typically written in Sass
├── tools                     # Node scripts that run build related tools
│   ├── build.js              # Runs the production build
│   ├── buildHtml.js          # Builds index.html
│   ├── distServer.js         # Starts webserver and opens final built app that's in dist in your default browser
│   ├── srcServer.js          # Starts dev webserver with hot reloading and opens your app in your default browser
└── webpack.config.js         # Configures webpack

###Where are the files being served from when I run npm start? Webpack serves your app in memory when you run npm start. No physical files are written. However, the web root is /src, so you can reference files under /src in index.html. When the app is built using npm run build, physical files are written to /dist and the app is served from /dist.

###How is Sass being converted into CSS and landing in the browser? Magic! Okay, more specifically, we're handling it differently in dev (npm start) vs prod (npm run build)

When you run npm start:

1. The sass-loader compiles Sass into CSS
2. Webpack bundles the compiled CSS into bundle.js. Sounds odd, but it works!
3. bundle.js contains code that loads styles into the <head> of index.html via JavaScript. This is why you don't see a stylesheet reference in index.html. In fact, if you disable JavaScript in your browser, you'll see the styles don't load either.

The approach above supports hot reloading, which is great for development. However, it also create a flash of unstyled content on load because you have to wait for the JavaScript to parse and load styles before they're applied. So for the production build, we use a different approach:

When you run npm run build:

1. The sass-loader compiles Sass into CSS
2. The extract-text-webpack-plugin extracts the compiled Sass into styles.css
3. buildHtml.js adds a reference to the stylesheet to the head of index.html.

For both of the above methods, a separate sourcemap is generated for debugging Sass in compatible browsers.

###I don't like the magic you just described above. I simply want to use a CSS file. No problem. Reference your CSS file in index.html, and add a step to the build process to copy your CSS file over to the same relative location /dist as part of the build step. But be forwarned, you lose style hot reloading with this approach.

I just want an empty starter kit.

This starter kit includes an example app so you can see how everything hangs together on a real app. To create an empty project, you can delete the following:

1. Components in src/components
2. Styles in src/styles/styles.scss
3. Delete files in src/businessLogic

Don't want to use Redux? See the next question for some steps on removing Redux.

Do I have to use Redux?

Nope. Redux is useful for applications with more complex data flows. If your app is simple, Redux is overkill. Remove Redux like this:

1. Delete the following folders and their contents: actions, constants, reducers, containers, store
2. Uninstall Redux related packages: npm uninstall redux react-redux redux-thunk
3. Remove Redux related imports from /src/index.js: import configureStore from './store/configureStore';, import App from './containers/App'; and import { Provider } from 'react-redux';
4. Remove this line from /src/index.js: const store = configureStore();
5. Delete components in /components and create a new empty component.
6. Replace the call to <Provider><App/></Provider> in /src/index.js with a call to the new top level component you just created in step 5.

How do I deploy this?

npm run build. This will build the project for production. It does the following:

• Minifies all JS
• Sets NODE_ENV to prod so that React is built in production mode
• Places the resulting built project files into /dist. (This is the folder you'll expose to the world).

Why are test files placed alongside the file under test (instead of centralized)?

Streamlined automated testing is a core feature of this starter kit. All tests are placed in files that end in .spec.js. Spec files are placed in the same directory as the file under test. Why?

• The existence of tests is highly visible. If a corresponding .spec file hasn't been created, it's obvious.
• Easy to open since they're in the same folder as the file being tested.
• Easy to create new test files when creating new source files.
• Short import paths are easy to type and less brittle.
• As files are moved, it's easy to move tests alongside.

That said, you can of course place your tests under /test instead, which is the Mocha default. If you do, you can simplify the test script to no longer specify the path. Then Mocha will simply look in /test to find your spec files.

How do I debug?

Since browsers don't currently support ES6, we're using Babel to compile our ES6 down to ES5. This means the code that runs in the browser looks different than what we wrote. But good news, a sourcemap is generated to enable easy debugging. This means your original JS source will be displayed in your browser's dev console. Note: When you run npm start, no JS is minified. Why? Because minifying slows the build. So JS is only minified when you run the npm run build script. See more on building for production below.

Also note that no actual physical files are written to the filesystem during the dev build. For performance, all files exist in memory when served from the webpack server.. Physical files are only written when you run npm run build.

Tips for debugging via sourcemaps:

1. Browsers vary in the way they allow you to view the original source. Chrome automatically shows the original source if a sourcemap is available. Safari, in contrast, will display the minified source and you'll have to cmd+click on a given line to be taken to the original source.
2. Do not enable serving files from your filesystem in Chrome dev tools. If you do, Chrome (and perhaps other browsers) may not show you the latest version of your code after you make a source code change. Instead you must close the source view tab you were using and reopen it to see the updated source code. It appears Chrome clings to the old sourcemap until you close and reopen the source view tab. To clarify, you don't have to close the actual tab that is displaying the app, just the tab in the console that's displaying the source file that you just changed.
3. If the latest source isn't displaying the console, force a refresh. Sometimes Chrome seems to hold onto a previous version of the sourcemap which will cause you to see stale code.

I'm getting an error when running npm install: Failed to locate "CL.exe"

On Windows, you need to install extra dependencies for browser-sync to build and install successfully. Follow the getting started steps above to assure you have the necessary dependencies on your machine.

I can't access the external URL for Browsersync

To hit the external URL, all devices must be on the same LAN. So this may mean your dev machine needs to be on the same Wifi as the mobile devices you're testing.

###What about the Redux Devtools? They're not included at this time to keep the project simple. If you're interested, Barry Staes created a branch with the devtools incorporated.