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

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 - Udacity Alumni App (GraphQL on Rails) - Clientside code - Serverside code - Live App coming soon - v3.0 (GraphQL on Rails) - See the server code - Clientside code - See the live app (Beta) - Meetup Event Planner (GraphQL on Rails) - See the Code - See the Live App - React Weekly (GraphQL JavaScript) - See the Code - See the Live App - Corporate Dashboard (GraphQL JavaScript) - See the Code - See the Live App - Restaurant Reviewer (No GraphQL) - See the Code - See the Live App

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


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
  5. GraphQL

    • GraphQL increases performance by eliminating expensive over-fetching
  6. Service Worker / Offline First

    • The only requirement to go offline first is using SSL.
  7. 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.


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

  2. Install dependencies

    npm run setup


    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


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. . ├── ├── 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


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


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


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.


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

Related Repositories



:fire: A highly scalable, offline-first foundation with the best developer experience and a focus on performance and best practices. ...



:fire: A highly scalable, offline-first foundation with the best developer experience and a focus on performance and best practices. ...



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



:star: Scalable micro-framework featuring React and TypeScript ...



:fire: A highly scalable, offline-first foundation with the best developer experience and a focus on performance and best practices. ...