For developers

Technologies used:

Universal rendering with async data fetching.
React as the view.
React Router v4 as the router.
Redux's futuristic Flux implementation.
Express server.
Webpack 3 for bundling and "Tree-Shaking" support.
Babel for ES6 and ES7 transpiling.
React Hot Loader 4 to tweak React components in real time.
nodemon to monitor for any changes in your node.js application and automatically restart the server.
axios for universal data fetching/rehydration on the client.
redux-thunk as the middleware to deal with asynchronous action.
react-router-redux to keep your router in sync with Redux state.
react-helmet to manage title, meta, styles and scripts tags on both server and client.
webpack-isomorphic-tools to allow require() work for statics both on client and server.
Webpack Dev Middleware serves the files emitted from webpack over the Express server.
Webpack Hot Middleware allows you to add hot reloading into the Express server.
Webpack Bundle Analyzer creates a visualize size of webpack output files with an interactive zoomable treemap.
morgan the HTTP request logger for server side debugging.
Redux Devtools Extension for next generation developer experience.
Flow as the static type checker for javascript.
ESLint to maintain a consistent javascript code style (Airbnb + Prettier).
StyleLint to maintain a consistent css/scss code style.
CSS and SASS support with PostCSS for advanced transformations (e.g. autoprefixer). CSS modules enabled.
Image (with image-webpack-loader for optimizing) and Font support.
Split vendor's libraries from client bundle.
No other view engines, just javascript based HTML rendering component.
Shared app config between development and production.
404 error page and redirect handling.
Yarn as the package manager.

Requirements

node >= 6.0
npm >= 3.0

Getting Started

1. You can start by cloning the repository on your local machine by running:

git clone https://github.com/containerum/ui.git
cd ui

2. Install all of the dependencies:

yarn

3. Start developer mode:

yarn build    # Run once
yarn start

Now the app should be running at http://localhost:3001/

4. Start production mode:

yarn start:production    # Building bundle and running production server

For production mode app should be running at http://localhost:8080/

Note: You can change the port that you want from ./package.json.

NPM Script Commands

I use better-npm-run to manage the scripts in a better way, which also provides the compatibility of cross-platform. All of the scripts are listed as following:

`yarn <script>`	Description
`start`	Run your app on the development server at `localhost:3001`. HMR will be enabled.
`start:production`	Bundle files to `./public/assets` and run it on the production server at `localhost:8080`.
`start:prod`	Run your app on the production server only at `localhost:8080`.
`start:production:docker`	Bundle files to `./public/assets` and run app on the production in container at `localhost:3000`.
`start:prod:docker`	Run your app on the production server in container at `localhost:3000`.
`build`	Remove the previous bundled files and bundle it to `./public/assets`.
`build:stats`	Visualize the contents of all your bundles.
`lint`	Lint all `.js` and `.scss` files.
`lint:js`	Lint all `.js` files (Use `--fix` to auto fix eslint errors).
`lint:style`	Lint all `.scss` files (Use `--fix` to auto fix stylelint errors).
`flow`	Run type checking for `.js` files.
`flow:stop`	Stop type checking.
`clean:all`	Remove the client/server bundled stuff and the coverage report.
`clean:build`	Remove the `./public/assets` folder to clean the client bundled files.
-------------------------	-------------------------------------------------------------------------------------------------

App Structure

Here is the structure of the app, which serves as generally accepted guidelines and patterns for building scalable apps.

.
├── public                          # Express server static path/Webpack bundled output
│   └── favicon.ico                 # Favicon is placed in the same path with the main HTML page
├── src                             # App source code
│   ├── config                      # App configuration settings
│   │   ├── default.js              # Default settings
│   │   ├── index.js                # Configuration entry point
│   │   └── prod.js                 # Production settings (overrides the default settings)
│   ├── components                  # Reusable components (including scss files)
│   ├── containers                  # Container components (including scss files)
│   ├── actions                     # Redux actions
│   ├── reducers                    # Redux reducers
│   ├── utils                       # App-wide utils (e.g. HTML component)  
│   ├── theme                       # App-wide style and vendor CSS framework
│   ├── types                       # Flow types for reducer, action, state, store
│   │── configureStore.js           # Configure and instrument Redux store
│   ├── client.js                   # App bootstrap and rendering (webpack entry)
│   ├── routes.js                   # Routes configuration for both client and server side
│   └── server.js                   # Express server (with webpack dev/hot middlewares)
├── tools                           # Project related configurations (build etc.)
│   ├── flow                        # Flow types, interface, module aliasing definitions
│   ├── openBrowser                 # Utility for opening Google Chrome
│   ├── jest                        # Jest CSS modules and assets mocks settings
│   ├── webpack                     # Webpack settings
│   │   ├── config.babel.js         # Webpack configuration
│   │   └── WIT.config.js           # Webpack Isomorphic Tools configuration file
└── index.js                        # App entry point

Server-Side Security and Performance

Concerning the security and performance of Express in production, there is already some middleware setup for you:

helmet - Helps secure Express server with various HTTP headers.
hpp - Express middleware to protect against HTTP Parameter Pollution attacks.
compression - Gzip compression support for speeding up Express server responses.

Note: It's just a basic protected mechanism for your app, you can see the security best practices for more advanced configuration.

Setup Redux DevTools Extension

The Redux Devtools Extension let us wire up our Redux app to a time-traveling debugger. It's enabled in development only. You can follow these installation guides to use it:

For Chrome

from Chrome Web Store;
or build it with npm i && npm run build:extension and load the extension's folder ./build/extension;
or run it in dev mode with npm i && npm start and load the extension's folder ./dev.

For Firefox

from Mozilla Add-ons;
or build it with npm i && npm run build:firefox and load the extension's folder ./build/firefox (just select a file from inside the dir).

For Electron

just specify REDUX_DEVTOOLS in electron-devtools-installer.

For other browsers and non-browser environment

use remote-redux-devtools.

Overview

Stateless Functional Components

React 0.14 introduced a simpler way to define components called stateless functional components. These components are written in plain javascript functions. In the starter boilerplate I use it wherever possible.

Adding Routes

This starter use React Router v4 library to manage our routes. You can setup your routes in ./src/routes.js. For example:

import MyRouteComponent from './containers/MyRouteComponent';

// ...

export default [
  {
    // Define your route path
    path: '/myPath',
    // If the route matches the location.pathname exactly or not (used for index route usually)
    exact: true,
    // Add your route component here
    component: MyRouteComponent,
    // Add your sub route component here
    routes: [
      {
        path: '/myPath/mySubPath',
        component: MySubRouteComponent
      }
    ]
    // ...
  }
  // Setup other routes...
];

Data Fetching from Server-side

Just write Redux actions and stores as normal (read the Redux guide if you are new). The starter using axios as the data fetcher, it's quite simple and easy to use. If the action creator is asynchronous then it will return a Promise (or a Promise.all) in the inner function.

Register the action(s) in ./src/routes.js, which have to be called from server-side:

// ...

export default [
  {
    // ...
    loadData: dispatch =>
      Promise.all([
        // Register your server-side call action(s) here
        dispatch(myReduxAction())
      ])
  }
  // ...
];

The action(s) will be dispatched through ./src/server.js on server-side:

// ...

app.get('*', (req, res) => {
  // ...

  // Here's the method for loading data from server-side
  const loadBranchData = (): Promise<*> | Object => {
    const promises = [];

    routes.some(route => {
      const match = matchPath(req.url, route);

      // $FlowFixMe: the params of pre-load actions are dynamic
      if (match && route.loadData)
        promises.push(route.loadData(store.dispatch, match.params));

      return match;
    });

    return Promise.all(promises);
  };

  // ...
});

// ...

On client-side, don't forget to invoke the action(s) in componentDidMount. This ensures that if the component is reached on the client, then the same actions will be invoked. It's up to the action(s) to figure out if fetches for data need to be made or not:

componentDidMount() {
  // Invoke your redux action(s) for client rendering
  this.props.myReduxAction();
}

Managing Title, Meta, Styles and Scripts

The parent App.js defines the base title and meta in a <Helmet {...config.app} /> component. Any sub-component can override/add properties (supports meta, link, script, style tags and html attributes). See the react-helmet documents for more info.

App config

You can store app settings under ./src/config. By default the default.js will be loaded. If the process.env.NODE_ENV matches to production, the prod.js will be used instead, and it inherits the data info from default.js.

You can access the correct config with:

import config from './config';

Styles

The starter supports CSS, SASS and CSS modules is enabled by default. I use PostCSS plugin to parse CSS and add autoprefixer to your stylesheet. You can access your stylesheet with two ways.

With CSS modules:

import styles from './styles.scss';

// ...

render() {
  return (
    <div className={styles.myClass}>   // The className matches one of CSS classes in your SCSS file
      <Helmet title="Home" />
      {this.renderUserList()}
    </div>
  );
}

Without CSS modules (you need to turn off CSS modules from ./tools/webpack/config.babel.js):

import index.scss;

// ...

render() {
  return (
    <div className="myClass">    // Use the CSS class as normal
      <Helmet title="Home" />
      {this.renderUserList()}
    </div>
  );
}

By the way, if you want to use your based style or a vendor CSS framework, just import it through the ./src/containers/App/index.js file, for example:

import '../../theme/normalize.css'; // Import a vendor stylesheet here
import styles from index.scss; // Import your based stylesheet here

export default routes => {
  // ...
};

For the better development experience, don't forget to include those files in the ./src/utils/Html.js, for example:

// ...

  {
    _.keys(assets.styles).length === 0 ?
      <style
        dangerouslySetInnerHTML={{ __html:
          // Include the vendor CSS framework and your own style here
          require('../theme/normalize.css')._style +
          require('../containers/App/styles.scss')._style +
          // Other styles...
        }}
      />
      : null
  }

// ...

Image and Font

It's super easy to render the image and font both on client and server, the usage would be like below.

Using image:

// Require an image
<img src={require('./assets/logo.svg')} alt="Logo" role="presentation" />

Using font-awesome:

// With CSS modules
import styles from './styles.scss';

// ...

return (
  <div>
    <div>
      <i className={styles.iconUser} /> Welly
    </div>
  </div>
);

// Without CSS modules
import './font-awesome.css';

// ...

return (
  <div>
    <div>
      <i className="fa fa-user" /> Welly
    </div>
  </div>
);

For using CSS modules, you have to set the proper font path in your scss/sass file:

$fa-font-path:"../node_modules/font-awesome/fonts";
@import "../node_modules/font-awesome/scss/font-awesome";
.icon-user {
  @extend .fa;
  @extend .fa-user;
}

Boost App Performance by Shallow Compare

If your React component's render() function renders the same result given the same props and state, you can use React.PureComponent for performance boost.

React.PureComponent is exactly like React.Component but implements shouldComponentUpdate() with a shallow prop and state comparison. See the Optimizing Performance topic for more info.

How we implemented the optimizing:

import React, { PureComponent } from 'react';

// ...

class Home extends PureComponent {
  // Use PureComponent instead of Component
  // ...
}

Type Checking by Flow

Flow, a static type checker for javascript. It adds static typing to javascript to improve developer productivity and code quality. In particular, static typing offers benefits like early error checking, which helps you avoid certain kinds of runtime failures, and code intelligence, which aids code maintenance, navigation, transformation, and optimization.

Flow’s static analysis makes building web apps with React safe by tracking the types of props and state. Flow understands which props are required and also supports default props.

I love to write React, Redux with Flow, I know it's not easy to learn at the beginning. But trust me, it's worth to learn. There're some useful instructions that I can give you as below:

If you are new to Flow, read the official docs to understand it.
Learn how to use Flow with React from here.
Here's an example, which shows you the overall concept of integrating Flow with Redux.

Moreover, often you will want to use third-party libraries. For these circumstances, Flow supports the concept of a "libdef" ("Library Definition") which allows you to describe the interface and types of the library separate from the library and without needing to add types to or change the library itself. You can write a libdef file yourself if you need to or use flow-typed, which is a repository of third-party library interface definitions for use with Flow.

Note: If you don't want to use Flow, just remove the /* @flow */ comment and related typing definitions from each javascript file.

JavaScript and Style Lint

JavaScript lint and style lint are included into webpack compiling for runtime checking. If you want them to terminate webpack build process while an error occurs, you can enable those from ./tools/webpack/config.babel.js (Default: false):

// ...

// Enable build process terminated while there's an eslint error
const eslint = true;
// Enable build process terminated while there's an stylelint error
const stylelint = true;

// ...

You can also use istanbul's ignore hints to specify specific lines of code in a javascript file to skip code coverage.

Troubleshooting

If you get the the following message during developing, try to run yarn build to create the necessary webpack-assets.json file for enable related assets (e.g. javascript, styles, image etc.) working on universal rendering.

webpack-isomorphic-tools (waiting for the first webpack build to finish)

If you encounter the markup mismatches error (it's a react universal issue, which usually occurs due to the non-synchronized rendering result between client and server), you can do:
- Restart the server to solve it.
- Or for v16.1.0 up, you can use suppressHydrationWarning attribute for intentional client/server text mismatches (#11126).
If you run the starter through a cloud computing service such as AWS EC2 instance etc. and you encounter an UnhandledPromiseRejectionWarning like this issue. It might be caused by the "openBrowser" tool. You can solve the issue as follows.

In the ./package.json script:

// ...

"start:prod": {
  "command": "node ./index.js",
  "env": {
    "NODE_PATH": "./src",
    "NODE_ENV": "production",
    "PORT": 8080,
    "BROWSER": "none"   // Add this node variable to turn off the open browser util
  }
},

// ...

If you are on windows and encounter the following error: Expected linebreaks to be 'LF' but found 'CRLF' linebreak-style. The following rule must be added to ./package.json.

"linebreak-style": 0

So it will look like:

// ...
 "rules": {
      "linebreak-style": 0,
      "global-require": 0,
// ...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

development.md

development.md

For developers

Technologies used:

Requirements

Getting Started

NPM Script Commands

App Structure

Server-Side Security and Performance

Setup Redux DevTools Extension

Overview

Stateless Functional Components

Adding Routes

Data Fetching from Server-side

Managing Title, Meta, Styles and Scripts

App config

Styles

Image and Font

Boost App Performance by Shallow Compare

Type Checking by Flow

JavaScript and Style Lint

Troubleshooting

Files

development.md

Latest commit

History

development.md

File metadata and controls

For developers

Technologies used:

Requirements

Getting Started

NPM Script Commands

App Structure

Server-Side Security and Performance

Setup Redux DevTools Extension

Overview

Stateless Functional Components

Adding Routes

Data Fetching from Server-side

Managing Title, Meta, Styles and Scripts

App config

Styles

Image and Font

Boost App Performance by Shallow Compare

Type Checking by Flow

JavaScript and Style Lint

Troubleshooting