/scalable-react-boilerplate

:star: Scalable feature-first React micro-framework made for Udacity Alumni collaborative projects

Primary LanguageJavaScriptMIT LicenseMIT

No longer maintained

Not Maintained

Sadly, this repository will no longer be maintained. The contributors are no longer able to devote time to managing an open source community. The source code will remain here to serve as an example for the community and will accept pull requests for bug fixes.

Scalable Boilerplate Logo

Scalable React Boilerplate

npm version Code Ship Codacy grade

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

You can read more about the organizational strategy used in this app in this Medium post.

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

TypeScript Version

We now have a TypeScript version of this project. See here.

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 the same folder. With 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!

If this is confusing, don't fret, we've set you up with a few examples and code generation tools. Give it a try! We promise you will enjoy it.

Example Apps

Below are a few example apps that have been built with this project

NOTE: if you are using this boilerplate in production, we want to know! Leave an issue, or submit a PR and we will merge it in. Thanks!

Main Features

Styled Components

This framework employs both css-modules and styled-components. We feel that styled-components is the best css-in-js library available.

Grommet

Grommet is the world's most advanced UX framework. It contains hundreds of reusable UI components that you can use right away.

GraphQL / Apollo

This framework includes some basic setup for GraphQL and ApolloClient. You will have to setup your own GraphQL Server. Alternatively, take a look at the GraphQL Anywhere package (not installed), which would allow you to process GraphQL queries client-side.

The setup includes the ability to generate the boilerplate to create GraphQL / ApolloClient queries and mutations within your containers. It also adds the eslint-graphql-plugin to lint your collocated GraphQL queries / mutations. The way it works is to load a schema.json file to create an AST of your GraphQL schema. You will need to provide your own schema.json file and leave it in the /config/schema/ folder.

Take a look at the Example Apps section to see examples of GraphQL configuration in practice.

If you do not need to use graphql, take a look at the sans-apollo branch for a reference implementation without GraphQL / Apollo.

Experimental Features

Flow

Static types are all the rage in Front End JavaScript land right now.

We feel that the use of Static types is paramount in the evolution of JavaScript and as such have integrated the Flow static type-checking library.

The nice thing about Flow is that you can gradually introduce it into your app, much like we have done with the example code of this boilerplate. You can see a couple of examples of Flow in use in the project in the components directory. If this is not a feature you desire, then do not add the // @flow comment in any files.

We have provided library definitions within the config/flow-typed folder and have also provided some useful configuration within the .flowconfig file.

Performance Optimizations

This framework takes performance very seriously and includes a whole slew of performance optimizations out of the box. We have benchmarked the initial time to first byte at under 20ms! Below is a brief enumeration of the main performance optimizations we employ by default.

  1. Webpack code chunking

  2. Lazy React Router Route Loading

  3. Serverside Rendering

  4. Reselect

  • Memoization and React.PureComponent
  1. GraphQL
  • GraphQL increases performance by eliminating expensive over-fetching
  1. Service Worker / Offline First
  • The only requirement to go offline first is using SSL.
  1. Immutable JS
  • Immutable JS is installed by default, but not used in the example application. By combining React.PureComponent, reselect and immutable.js, you will get some serious rendering performance enhancements.

Documentation

Getting Started

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

There are two options for installation:

  1. Clone repo

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

  2. Install dependencies

    npm run setup

    --or--

    With Yarn installed globally, run npm run setup:yarn

  3. Create environment file In order for the server and client to know which urls to connect to, we ask that you make a .env file. We've included a .env.example file that you can rename to get started with the default values.

    cp .env.example .env

  4. Run development server

    npm run start

    Your app will be served at: http://localhost:1337

Deployment

A demo ExpressJS setup is included with the app. The express server will serve up the production minified bundle.js, index.html and any other assets that are located in the /server/public folder.

The deploy script is now totally automated and will hook into the server-rendering automatically. Running npm run serve:bundle will set your environment to production and serve these files via Express. Also, a Procfile is included, which will run the Express server on Heroku when you push your code.

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 within the /server/public folder

  • npm run clean

    • Removes the bundled code and the production ready files

  • npm run serve:bundle

    • Serve production assets from the /server/public folder.

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
    • Styled Components
    • Reducers, actions and constants
    • GraphQL: The generator can add collocated queries and mutations using GraphQL / ApolloClient. Accept the option to use this feature.
    • 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
    • Styled Components
    • 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
    • Container Import: Most of the time, a Route exists only to import a container by the same name. This is enabled by default, so make sure to run the container generator if you want to use this feature.

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 any comment that is prefixed with GENERATOR and things will work great. See below for an example.

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

/* GENERATOR: Assemble all containers for export */
export LandingContainer from './LandingContainer';
export AppContainer from './AppContainer';

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 using Jest. A number of testing utilities are included, including

  • Expect (Plus Expect-JSX)
  • Chai (JSX and Immutable)
  • Enzyme
  • Jest & enzyme-to-json in order to use the Jest snappshotting with Enzyme.

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 Jest.

Technologies / Libraries

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
  • Setup production server configuration
  • Add Jest as testing utility
  • Incporporate Server Rendering
  • Create Docker container & automation scripts
  • Write wiki / other documentation

Acknowledgements

Udacity Alumni Loves React

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:

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 in this project, especially the feature-first architectural pattern, were reverse engineered from the same project.

Troubleshooting

The most often reason for an error is a mismatch in node and npm versions. In the case of this project, we are using Node version 5.2.0.

Instructions for installing NVM and setting your node version for the project can be found here.

If you get an error message, such as "Unexpected token import", that means that your Babel installation is not working right. Please see here for potential troubleshooting steps.

Dev Tools

Redux and Apollo Dev Tools

Integrated in this project are two amazing dev tools, for Redux and for Apollo / GraphQL.

Redux Dev Tools

Please install the Redux Dev Tools chrome extension. The dev tools extension is configured within the /app/src/store.js file and will automatically bootstrap to your store.

screen shot 2016-12-16 at 4 22 37 pm screen shot 2016-12-16 at 4 22 20 pm

Apollo Dev Tools

If you are using Apollo and have a GraphQL server setup, you will be able to benefit from the Apollo Dev Tools. For more information, read this Medium article and install the chrome extension to start using the tools today.

screen shot 2016-12-16 at 4 16 19 pm screen shot 2016-12-16 at 4 19 33 pm