Start your next react project in seconds

A highly scalable, offline-first foundation with the best DX and a focus on performance and best practices

_{Created by Max Stoiber and maintained with ❤️ by an amazing team of developers.}

Differences from react-boilerplate

This project is a fork of react-boilerplate with experimental support for plugins. See react-redux-auth0-plugin for an example, and the Plugins section below on how to use plugins.

Plugins

Plugins allow additional features to be added to the application. A plugin may include:

• Reducers
• Sagas
• Components (container and simple)
• Selectors
• Actions

Following are the steps to install and activate a plugin, using react-redux-auth0-plugin as an example:

1. Add the plugin to pluginsConfig.js along with any plugin-specific configuration entries

Copy pluginsConfig-sample.js to pluginsConfig.js, uncomment the sample configuration for the react-redux-auth0-plugin, and set clientId, domain, redirectUrl with values for your Auth0 account and application.

cp app/pluginsConfig-sample.js app/pluginsConfig.js
# Edit app/pluginsConfig.js

2. Add the plugin dependency

Add the react-redux-auth0-plugin dependency.

yarn add react-redux-auth0-plugin

3. Update pages to use plugin components as needed

Edit app/containers/HomePage/index.js to add the sample auth controls from react-redux-auth0-plugin:

import { ConnectedAuthControls } from 'react-redux-auth0-plugin';

...

  // Add to JSX:
        <div>
          <ConnectedAuthControls/>
        </div>

4. Update any routes that depend on the plugins

Modify app/routes.js to include the plugin sagas for any routes that need to use the plugin. Note in the code below how the plugin global saga modules are concatenated to the other modules, then the sagas are extracted from the saga modules.

    {
      path: '/',
      name: 'home',
      getComponent(nextState, cb) {
        const importModules = Promise.all([
          import('containers/HomePage/reducer'),
          import('containers/HomePage'),
          import('containers/HomePage/sagas'),
        ].concat(getGlobalSagaModules()));

        const renderRoute = loadModule(cb);

        importModules.then(([reducer, component, ...sagaModules]) => {
          injectReducer('home', reducer.default);
          const sagas = extractSagas(sagaModules);
          injectSagas(sagas);

          renderRoute(component);
        });

        importModules.catch(errorLoading);
      },

5. Test

You should now see a 'Login' link on the home page (e.g. 'http://localhost:3000/'). When you click on it, it should pop-up the Auth0 login dialog. Once logged in, the page will refresh, show your user nickname from Auth0, and show a Logout button.

Plugins: how they work

Plugins get an opportunity to provide additional behavior at certain lifecycle points, specifically:

• Init: Invoked when the app is initializing, from app/app.js
• Post-application init: Invoked when the app has loaded. Called from app/app.js
• Global reducers: Reducers returned by getGlobalReducers() are included in every route
• Global sagas: Sagas returned by getGlobalSagaModules() are included in every route

Features

Quick scaffolding

Create components, containers, routes, selectors and sagas - and their tests - right from the CLI!

Instant feedback

Enjoy the best DX (Developer eXperience) and code your app at the speed of thought! Your saved changes to the CSS and JS are reflected instantaneously without refreshing the page. Preserve application state even when you update something in the underlying code!

Predictable state management

Unidirectional data flow allows for change logging and time travel debugging.

Next generation JavaScript

Use template strings, object destructuring, arrow functions, JSX syntax and more, today.

Next generation CSS

Write composable CSS that's co-located with your components for complete modularity. Unique generated class names keep the specificity low while eliminating style clashes. Ship only the styles that are on the page for the best performance.

Industry-standard routing

It's natural to want to add pages (e.g. `/about`) to your application, and routing makes this possible.

Industry-standard i18n internationalization support

Scalable apps need to support multiple languages, easily add and support multiple languages with `react-intl`.

Offline-first

The next frontier in performant web apps: availability without a network connection from the instant your users load the app.

SEO

We support SEO (document head tags management) for search engines that support indexing of JavaScript content. (eg. Google)

But wait... there's more!

• The best test setup: Automatically guarantee code quality and non-breaking changes. (Seen a react app with 99% test coverage before?)
• Native web app: Your app's new home? The home screen of your users' phones.
• The fastest fonts: Say goodbye to vacant text.
• Stay fast: Profile your app's performance from the comfort of your command line!
• Catch problems: AppVeyor and TravisCI setups included by default, so your tests get run automatically on Windows and Unix.

There’s also a fantastic video on how to structure your React.js apps with scalability in mind. It provides rationale for the majority of boilerplate's design decisions.

_{Keywords: React.js, Redux, Hot Reloading, ESNext, Babel, react-router, Offline First, ServiceWorker, styled-components, redux-saga, FontFaceObserver}

Quick start

1. Clone this repo using git clone --depth=1 https://github.com/react-boilerplate/react-boilerplate.git
2. Run npm run setup to install dependencies and clean the git repo.
   We auto-detect yarn for installing packages by default, if you wish to force npm usage do: USE_YARN=false npm run setup
   At this point you can run npm start to see the example app at http://localhost:3000.
3. Run npm run clean to delete the example app.

Now you're ready to rumble!

Please note that this boilerplate is production-ready and not meant for beginners! If you're just starting out with react or redux, please refer to https://github.com/petehunt/react-howto instead. If you want a solid, battle-tested base to build your next product upon and have some experience with react, this is the perfect start for you.

Documentation

• The Hitchhikers Guide to react-boilerplate: An introduction for newcomers to this boilerplate.
• Overview: A short overview of the included tools
• Commands: Getting the most out of this boilerplate
• Testing: How to work with the built-in test harness
• Styling: How to work with the CSS tooling
• Your app: Supercharging your app with Routing, Redux, simple asynchronicity helpers, etc.

Supporters

This project would not be possible without the support by these amazing folks. Become a sponsor to get your company in front of thousands of engaged react developers and help us out!

---

License

This project is licensed under the MIT license, Copyright (c) 2017 Maximilian Stoiber. For more information see LICENSE.md.