athmangude / scalable-react-boilerplate

:star: Scalable feature-first React boilerplate and component generator made for Udacity Alumni collaborative projects

Scalable React Boilerplate

The boilerplate aims to follow best practices for building highly scalable and reusable apps and component libraries with React and cutting edge JavaScript.

Following the lead of the famous React Boilerplate project, this starter project incorporates the Feature-first architecture, meaning that files are organized by the feature they implement, not the filetype. This provides a mechanism to scale React projects because it encourages isolation, encapsulation and reusability.

We incorporate an ESLint configuration and follow strictly the AirBnb JS & JSX style guides.

What is Feature First?

In most projects and frameworks, files are organized in a File type first fashion. For example, your tests exist in a test folder, your styles in a styles folder. This boilerplate takes a different approach.

We encourage encapsulation of features by asking that you organize each feature into a seperate folder (feature-first). In React, this means that your containers and components exist in their own folders, along with literally every other file that pertains to that one component. Your actions, reducers, tests, styles, and everything else are all internal to the component they represent. By decoupling your features from the rest of your app, you set yourself up to reuse your UI components in future projects. You can thank us later!

This may be confusing at first, but we've set you up with a few examples and code generation tools. Give it a try! We promise you will enjoy it.

Docker Support

Coming soon the app will support Docker, which will contain a configured web server to make deployment of this boilerplate simple! You can take a look at this branch for more details.

Documentation

Getting Started

To try the example application out or to use the project, follow the instructions below.

1. Clone repo

   git clone https://github.com/RyanCCollins/scalable-react-boilerplate.git

2. Install dependencies

   npm run setup

3. Run development server

   npm run start

   Development server should be running at http://localhost:8080/

4. Make build

   npm run build

File Structure

• Some files left out for brevity. Please reference the files in the Scalable React Boilerplate project for an example of the file structure. The application will ultimately be in use in a production web application project and more info will be posted here when we have production level examples.

.
├── README.md
├── LICENSE
├── index.html
├── package.json
├── webpack.config.js
├── app/
|   ├── fonts
|   ├── images
|   ├── src
|   |   ├── components
|   |   |   ├── FeatureFirstComponent
|   |   |   |   ├── index.js
|   |   |   |   ├── index.module.scss
|   |   |   |   └── tests
|   |   |   |   |   └── index.test.js
|   |   |   ├── App.jsx
|   |   |   ├── Main.js
|   |   |   └── index.js
|   |   ├── containers
|   |   |   ├── FeatureFirstContainer
|   |   |   |   ├── tests
|   |   |   |   |   ├── actions.test.js
|   |   |   |   |   ├── index.test.js
|   |   |   |   |   └── reducer.test.js
|   |   |   |   ├── actions.js
|   |   |   |   ├── constants.js
|   |   |   |   ├── index.js
|   |   |   |   ├── index.module.scss
|   |   |   |   └── reducer
|   |   |   └── index.js
|   |   ├── pages
|   |   ├── store
|   |   ├── utils
|   |   └── index.js
|   └── styles
├── .eslintignore
├── .eslintrc
├── .gitattributes
└── .gitignore

Scripts

• npm run setup

  Installs the application's dependencies

• npm run test

  Runs unit tests

• npm run test:watch

  Watches for changes to run unit tests

• npm run build

  Bundles the application

• npm run dev

  Starts webpack development server

• npm run lint

  Runs the linter

• npm run deploy

  Creates the production ready files

• npm run clean

  Removes the bundled code and the production ready files

Generators

The boilerplate contains generators for easy project scaffolding. At the moment, the generator has the following scaffold generating commands built in:

• Container npm run generate:container
  • Name: the name of the container, i.e. Awesome, which converts to: AwesomeContainer
  • Connected / Not connected ES6 Class containers (higher order)
  • SCSS Modules
  • Reducers, actions and constants
  • Tests for all of the above
  • README.md file that documents the container
• Component npm run generate:component
  • Name: the name of the component, i.e. Button
  • Stateless functional components (recommended)
  • ES6 class components
  • SCSS modules
  • Tests for all of the above
  • README.md file that documents the component
• Page npm run generate:page
  • Name: The name of the route, i.e. Home, which gets converted to HomePage
  • Route: the route that corresponds to the page

To run the generators with a list of options, run

npm run generate

Follow the on screen prompts to select the options you wish to use.

For convenience, you can bypass the initial selection and scaffold out containers, components and pages by running

npm run generate:<type_of_component>

where <type_of_component> is one of: component, container or page.

The generators use the same feature-first file organization as the rest of the project, encapsulating components within their own folder.

Gotchas

In order to get the import / export to work, the generator does some pattern matching of the comments in the files to place the new imports. Just don't delete the comments within the root level index.js file in each directory and things will work fine!

From app/src/container/index.js or app/src/component/index.js

// ... Other components here
import MyComponent from 'MyComponent';

export {
  // ... Other components here
  MyComponent
}

Configuring your own generators

For information on how to build your own generators with relative ease, please go to the Plop Microgenerator homepage for detailed instructions.

Testing

Included in the setup is a test suite that will run your tests in the browser using Karma. A number of testing utilities are included, including

• Expect (Plus Expect-JSX)
• Mocha
• Chai (JSX and Immutable)
• Enzyme
• Karma (including multiple Karma plugins)

You can see examples for testing of React Components, Redux Action Creators and Reducers in the repository here. Please follow the convention of naming tests with a .test.js postfix, or else the test suite will not recognize your tests.

To run tests, you will run

npm run test

which will pick up any file with the .test.js postfix and run it through Karma / Mocha, printing a report to the commandline.

Technologies / Libraries

• Node - JS runtime environment
• npm - package manager
• Babel - ES6 transpiler
• Webpack - module bundler & task runner
• React - interfaces
• react-hot-loader - hot reloading for react
• react-router - react application router
• react-redux - react bindings for redux
• react-css-modules - React CSS Modules implement automatic mapping of CSS modules.
• react-foundation - Foundation React components, use or don't use.
• Immutable - data structures
• Redux - awesome flux architecture
• Redux Form- works with React Redux to enable an html form in React to use Redux to store all of its state.
• redux-thunk - thunk middleware for redux
• isomorphic-fetch - API fetch network requests
• redux-devtools - redux development tool
• SASS - styles
• ESLint - linter
• Mocha - unit tests
• jsdom - vdom to test React without browser
• Expect - assertion library
• Enzyme - React Testing utils for rendering of components
• Chai / Immutable - assertion library for Immutable JS
• A bunch of useful scripts

Timeline / TODOS

• Write README file
• Write component tests using Enzyme
• Implement a Rails like component generator
• Add README.md files to each component
• Add Grommet as an optional starter component library
• Add Webpack stats plugin
• Dogfood the project and iterate on suggestions
• Create Docker container & automation scripts
• Write wiki / other documentation

Acknowledgements

This boilerplate began its life as a fork of the React Redux Simple Starter project and was setup as a starter project for the Udacity Alumni Web application open-source project.

It was created by several of the members of the Udacity Alumni product infrastructure team, including:

• Ryan Collins
• Andreas Daiminger

Many thanks to the team behind React Boilerplate, especially @maxstbr for setting a standard for the level of quality we in the React community can all learn from. Many of the ideas used here were reverse engineered from the same project.