React is a lightweight library, so to build real apps, you need more. This starter kit provides a comprehensive framework for building fast, testable applications with React. It offers a rich development experience including:

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

1. Initial Machine Setup
   First time running the starter kit? Then complete the Initial Machine Setup.
2. Clone the project
   Open the command line of your choice and change to the directory where you'd like to start your project. Then clone the project: git clone https://github.com/coryhouse/vin-react-starter-kit.git.
3. Rename directory
   Rename the 'vin-react-starter-kit' directory that was just created to your project's name.
4. Change directory
   cd into your projects root directory (the folder you just renamed).
5. Install Node packages
   npm install
6. Run the example app
   npm start 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.
7. 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.
8. 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. You can always refer to this repo for the example app code that you deleted.
9. Enable CORS on the APIs you need to call

##Initial Machine Setup

1. Install Node.
2. Install Git.
3. Install Python 2.7. Browser-sync (and various other Node modules) rely on node-gyp, which requires Python on Windows.
4. Install C++ Compiler. 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).
5. Configure your Editor for React. Install the appropriate plugin and configure your editor.
6. Add two lines to your Windows hosts file for motosnap.com:

127.0.0.1 motosnap.com
127.0.0.1 www.motosnap.com

The api configuration example (in /src/api/api.js) assumes that you're running VinConnect and its APIs locally at motosnap.com, so these host entries make sure cross origin calls like this succeed: motosnap.com/CarDashboard/API/CRMServiceBase/v1/customers/attachments/list?customerId=212746634

##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 also saves you from the long, painful process of wiring it all together into an automated dev environment.

###What command line should I use? This kit works on both the Windows DOS command line or in Git Bash on Windows. Git Bash is installed along with Git.

###How do I keep my app updated with the latest features of the starter kit? Be sure to clone this repo to get started. Then, anytime you want to get the latest version of this repo, type git pull on the command line in the root of your project. This will merge in all updates.

###Can you explain the folder structure? Note that the files that start with a dot below will be hidden by default in Windows. Here's how to see them. Or type ls -la in Git Bash.

.
├── .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.  
│   ├── api                   # Centralized place to make AJAX calls. Includes example call. 
│   ├── 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: Webpack handles it like this:

1. The sass-loader compiles Sass into CSS
2. Webpack bundles the compiled CSS into bundle.js. Sounds odd, but it works!
3. 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. This process is performed for both dev (npm start) and production (npm run build). Oh, and since we're generating source maps, you can even see the original Sass source 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.

###How do I call our existing Web APIs? This starter kit uses a Node based webserver (Webpack's dev server combined with Browsersync). This means you need to enable Cross-origin Resource Sharing (CORS) on any existing IIS hosted APIs so that you can call them from this kit's dev web server. Here's how:

Add this to your API's Global.asax:

protected void Application_BeginRequest(object sender, EventArgs e)
{
    EnableCrossOriginRequestsFromLocalhost(HttpContext.Current.Request);
}

/// <summary>
/// Enables calling IIS-based webservices on localhost from a separate webserver.
/// Useful for doing front-end development from a separate webserver such as a Node-based webserver.
/// </summary>
/// <param name="request"></param>
private void EnableCrossOriginRequestsFromLocalhost(HttpRequest request)
{
    if (!HttpContext.Current.Request.IsLocal) return;
    if (request.UrlReferrer == null) return; //can't set Access-Control-Allow-Origin header reliably without a referrer so just return. Referrer should always be set when being called from an app under development because the app under development's URL will be sent as the referrer automatically.
    var response = HttpContext.Current.Response;
    response.AddHeader("Access-Control-Allow-Origin", request.UrlReferrer.GetLeftPart(UriPartial.Authority));
    response.AddHeader("Access-Control-Allow-Credentials", "true");
    if (request.HttpMethod == "OPTIONS")
    {
        response.AddHeader("Access-Control-Allow-Methods", "POST, PUT, DELETE");
        response.AddHeader("Access-Control-Allow-Headers", "Content-Type, Accept");
        response.AddHeader("Access-Control-Max-Age", "1728000");
        response.End();
    }
}

The example project includes /api/api.js. This file uses Axios to make AJAX calls. It's recommended to centralize your API calls there. See the example in api.js. api.js properly sets the base url based on whether it's running locally, but be sure to add a hosts entry for motosnap.com (as outlined in the initial machine setup) to assure it works properly.

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

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.

Nope. Redux is useful for applications with more complex data flows. If your app is simple, Redux may be overkill. In that case, you can uninstall Redux and delete the following folders (and their contents):

• actions
• constants
• reducers
• containers
• store

Then, update index.js:

1. npm uninstall redux react-redux redux-thunk.
2. Remove the following imports: import configureStore from './store/configureStore'; and import { Provider } from 'react-redux';
3. Create a new top level component and reference it in the render method.

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.

Code coverage is calculated and reported via Istanbul. To view your current code coverage, run npm run open-coverage. This will open a tab in your default browser which displays code coverage statistics. You can optionally update the npm script config to run your code coverage on the command line each time you hit save.

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.

Before committing, type npm run build. This will setup 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).

In short, Gulp is an unnecessary abstraction that creates more problems than it solves. Here's why.

This assures that the build won't break when some new version is released. Unfortunately, many package authors don't properly honor Semantic Versioning, so instead, as new versions are released, I'll test them and then introduce them into the starter kit. But yes, this means when you do npm update no new dependencies will be pulled down. You'll have to update package.json with the new version manually.

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.

If you're in Webstorm, click the red x next to the terminal and then hit Alt+F12 to reopen the terminal. Unfortunately, Ctrl+C doesn't seem to work on the windows command line. (Another reason why I recommend using Git Bash).

To hit the external URL, all devices must be on the same LAN. So this means your dev machine needs to be on Wifi (since you likely can't connect any tablet or phone to Ethernet. If you dev machine is on wired ethernet, it's on a separate LAN from the Wifi so the two devices won't be able to communicate.

##Potential Features Coming Soon...

• Growl support when running tests and linting, plus associated docs
• Integrate ideas from React Starter Kit such like separate tool folder for scripts
• Integrate Karma for in-browser tests
• Run npm command or Yeoman generator to delete the example app
• Add coveralls and associated badges
• Make list of ideas to implement from: React-starter, Google's Web Starter Kit, React Starter Kit, Webpack React Starter, and HTML5 Boilerplate
• Integrate React testing tools
• Generate IDs automatically to assist QA automation
• Istanbul 1.0 Upgrade (to eliminate Isparta shim)
• Sass Linting
• Pagespeed
• Use Yeoman / npm for easy updates and config
• Babel 6 upgrade when babel-plugin-react-transform 2.0 comes out of beta
• Cache busting bundle naming
• GraphQL and Relay
• Organize with devops to run prod build step
• Bootstrap
• Authentication example
• Immutable.js
• Isomorphic Rendering