React Redux Boilerplate

Getting Started

$ git clone https://github.com/maxidela/react-redux-boilerplate.git
$ cd react-redux-boilerplate
$ npm install                   # Install project dependencies
$ npm start                     # Compile and launch

Application Structure

The application structure presented in this boilerplate is fractal, where functionality is grouped primarily by feature rather than file type. Please note, however, that this structure is only meant to serve as a guide, it is by no means prescriptive. That said, it aims to represent generally accepted guidelines and patterns for building scalable applications.

.
├── bin                      # Build/Start scripts
├── build                    # All build-related configuration
│   └── webpack              # Environment-specific configuration files for webpack
├── config                   # Project configuration settings
├── git-hooks                # All the git hooks (default one that runs karma pre-push)
├── server                   # Koa application (uses webpack middleware)
│   └── main.js              # Server application entry point
├── src                      # Application source code
│   ├── main.js              # Application bootstrap and rendering
│   ├── appcontainer         # Application container (Include Provider and Router)
│   ├── globals              # Application globals
│   │   ├── components       # Application global components
│   │   ├── containers       # Application global containers
│   │   └── modules          # Collections of global reducers/constants/actions
│   ├── layouts              # Components that dictate major page structure
│   ├── static               # Static assets (not imported anywhere in source code)
│   ├── styles               # Application-wide styles (generally settings)
│   ├── store                # Redux-specific pieces
│   │   ├── createStore.js   # Create and instrument redux store
│   │   └── reducers.js      # Reducer registry and injection
│   └── routes               # Main route definitions and async split points
│       ├── index.js         # Bootstrap main application routes with store
│       ├── Root.js          # Wrapper component for context-aware providers
│       └── Home             # Fractal route
│           ├── index.js     # Route definitions and async split points
│           ├── assets       # Assets required to render components
│           ├── components   # Presentational React Components
│           ├── container    # Connect components to actions and store
│           ├── modules      # Collections of reducers/constants/actions
│           └── routes **    # Fractal sub-routes (** optional)
└── tests                    # Unit tests

Development

Setting up git hooks

$ cp git-hooks/pre-push .git/hooks/
$ chmod +x .git/hooks/pre-push

While developing, you will probably rely mostly on npm start; however, there are additional scripts at your disposal:

npm run <script>	Description
start	Serves your app at localhost:3000. HMR will be enabled in development.
compile	Compiles the application to disk (~/dist by default).
test	Runs unit tests with Karma and generates a coverage report.
test:dev	Runs Karma and watches for changes to re-run tests; does not generate coverage reports.
deploy	Runs linter, tests, and then, on success, compiles your application to disk.
deploy:dev	Same as deploy but overrides NODE_ENV to "development".
deploy:prod	Same as deploy but overrides NODE_ENV to "production".
lint	Lint all .js files.
lint:fix	Lint and fix all .js files. Read more on this.

Testing

To add a unit test, simply create a .spec.js file anywhere in ~/tests. Karma will pick up on these files automatically, and Mocha and Chai will be available within your test without the need to import them. If you are using redux-cli, test files should automatically be generated when you create a component or redux module.

Coverage reports will be compiled to ~/coverage by default. If you wish to change what reporters are used and where reports are compiled, you can do so by modifying coverage_reporters in ~/config/index.js.

Deployment

Out of the box, this starter kit is deployable by serving the ~/dist folder generated by npm run deploy (make sure to specify your target NODE_ENV as well). This project does not concern itself with the details of server-side rendering or API structure, since that demands an opinionated structure that makes it difficult to extend the starter kit. However, if you do need help with more advanced deployment strategies, here are a few tips:

Static Deployments

If you are serving the application via a web server such as nginx, make sure to direct incoming routes to the root ~/dist/index.html file and let react-router take care of the rest. The Koa server that comes with the starter kit is able to be extended to serve as an API or whatever else you need, but that's entirely up to you.