Boilerplate to build a React app

1. General
2. Installation
3. Build Process: Development
4. Application Logic
5. Flux Data Flow: An Overview
6. Code Structure
7. Additional Resources

Tool Specs

• Node: 4.2.1
• NPM: 2.14.7
• React: 0.14.0

General

This application uses the following tools:

• Homebrew
• NVM
• Node.js 4.2.1
• npm 2.14.7
• Gulp and various Gulp plugins (gulp-imagemin, gulp-autoprefixer, etc.)
• React 0.14.6
• Alt
• Flux-style data management
• Webpack JavaScript compiler
• react-hot-loader Reload browser

Installation

Optional Node.js and npm installation via NVM

# Recommend installing NVM
$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.30.1/install.sh | bash

# Install Node and NPM
$ nvm install v4.2.0

# Set Node default
$ nvm alias default v4.2.0

Localhost

# clone the Git repository
$ git clone [email protected]:thebarbariangroup/pepsico-pepfeed.git

# change directory to the project folder
$ cd pepsico-pepfeed

# if node_modules folder is an alias, remove it
$ rm node_modules

# install the node modules
$ npm install

# build the code
$ gulp

In browser navigate to `localhost:3000`

File Structure

Once the application is installed, you'll find everything in the app folder:

app/
├── assets/
│   ├── fonts/
│   ├── icons/
│   ├── images/
│   ├── javascripts/
│   │   ├── App.js
│   │   ├── index.js
│   │   ├── __tests__/
│   │   ├── actions/
│   │   │   └── AppActions.js
│   │   ├── components/
│   │   ├── lib/
│   │   │   ├── alt.js
│   │   │   ├── Localization.js
│   │   │   ├── Config.js
│   │   │   └── API.js
│   │   ├── pages/
│   │   └── stores/
│   │       └── AppStore.js
│   ├── stylesheets/
│   │   ├── base/
│   │   ├── generated/
│   │   ├── components/
│   │   ├── mixins/
│   │   ├── pages/
│   │   ├── _components.scss
│   │   ├── _mixins.scss
│   │   ├── _pages.scss
│   │   ├── _base.scss
│   │   └── global.scss
│   └── localization/
│       └── en.json
└── views/
    └── index.html (bare bone html file where the css/js are loaded )

public/
├── assets/
│   ├── fonts/
│   ├── localization/
│   └── stylesheets/
└── index.html

Build Process:

$ gulp

You may need to alias gulp to node_modules/.bin/gulp, or npm install -g gulp.

Start editing assets and views from the gulp/assets folder. Files compile to public.

Code Structure

1. Actions

'use strict';
class AppActions {
  constructor () {
    this.generateActions(
        'updateContent',
        'toggleEditMode'
    )
  }
}

export default alt.createActions(AppActions)

---

2. Store

'use strict';
class AppStore {
  constructor () {
    this.bindListeners({
      updateContent: ActionCreator.UPDATE_CONTENT,
      toggleEditMode: ActionCreator.TOGGLE_EDIT_MODE
    })
  }
  ...
  updateContent(o) {
    this.data[o.field] = o.value
  }
}

export default alt.createStore(AppStore, 'AppStore');

---

3. View

'use strict';
import React, { Component }  from 'react';
import AppStore from '../stores/AppStore';
import ActionCreator from '../actions/AppActions';
import UI from './UI';
export default class Widget extends UI {
  constructor (props) {
    super(props);
    this.state = AppStore.getState();
    this._onChange = () => {
      this.setState( AppStore.getState() );
    }
  }
  componentWillMount () {
    AppStore.listen(this._onChange);
  }
  componentWillUnmount () {
    AppStore.unlisten(this._onChange);
  }
};

---

4. Implement View

'use strict';
import ActionCreator from '../actions/AppActions';
import Widget from '../components/Widget';
...
this.updateContent (object) {
  ActionCreator.updateContent(object)
},
...
...
<Widget onClick={ this.updateContent } />

Creating/Adding Icons

Inside this file: /app/assets/stylesheets/_icons.scss

You will see all of the icons' names that exist within the /app/assets/images/icons folder. Each name has the following syntax: icon-whatever-image-name

I add the precursor icon- to associate icons that have short names, like Bookmarks or Home.

When we create new icons, we add them to the same icons folder. After adding them, you must create the classes and reference their corresponding mixin as follows:

.icon-Home {
  @include get-sprite( Home );
}

This dynamically creates the icon, in retina, for the specified icon.

To use the icon within our DOM, I've created a JS Directive /app/assets/javascripts/components/Icon.js. When you want to use an Icon, simply write within your JSX markup.

This will dynamically create the following syntax: <span className="icon icon-whatever-image-name"/> I do this because if we want to change all Icons across the entire site, all we need to do is change this Icon.js file rather than going everywhere searching for all the instances.

Additional Resources

More information on the following:

• JSX: HTML in your JavaScript
• react-router
• Facebook's Flux overview
• Alt.js (Flux implementation): a user guide
• How to use Alt with React's lifecycle hooks
• Creating actions (events) with Alt/Flux
• Stores: your data warehouse