react-boilerplate/react-boilerplate

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

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

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.

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.

Static code analysis

Focus on writing new features without worrying about formatting or code quality. With the right editor setup, your code will automatically be formatted and linted as you work.

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 100% 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. Make sure that you have Node.js v8.15.1 and npm v5 or above installed.
2. Clone this repo using git clone --depth=1 https://github.com/react-boilerplate/react-boilerplate.git <YOUR_PROJECT_NAME>
3. Move to the appropriate directory: cd <YOUR_PROJECT_NAME>.
   
4. Run npm run setup in order to install dependencies and clean the git repo.
   At this point you can run npm start to see the example app at http://localhost:3000.
5. 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 Hitchhiker's 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.
• Troubleshooting: Solutions to common problems faced by developers.

Contributors

Thanks goes to these wonderful people (emoji key):

Max Stoiber 💻 📖 🤔 👀 ⚠️	Julien Benchetrit 💻 💬 📖 👀 🚧	Sara Federico 💻 👀 💬 📖 🚧	Justin Greenberg 💻 👀	Jon Winn 💻 👀	Johan Meester 💻 ⚠️ 📖	Yaroslav Kiliba 💻	Glen Ihrig 💻
Somasundaram Ayyappan 💻	Oliver Turner 💻	Samuel Sharpe 💻	Mihir Karandikar 💻	Vaibhav Verma 💻	Sébastien Dubois 💻	Chainarong Tangsurakit 💻	Amila Welihinda 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Supporters

This project would not be possible without the support of 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) 2019 Maximilian Stoiber. For more information see LICENSE.md.

react-boilerplate's Issues

Add component unit testing

https://blog.algolia.com/how-we-unit-test-react-components-using-expect-jsx/

Async Actions — Unit Testing

Since testing async actions isn't really useful, you have to export the non-async actions too to test them. This results in functions being exposed that shouldn't be. Example:

export function asyncChangeProjectName(name) {
  return function(dispatch) {
    return dispatch(changeProjectName(name));
  }
}

export function asyncChangeOwnerName(name) {
  return function(dispatch) {
    return dispatch(changeOwnerName(name));
  }
}

export function changeProjectName(name) {
  return { type: CHANGE_PROJECT_NAME, name };
}

export function changeOwnerName(name) {
  return { type: CHANGE_OWNER_NAME, name };
}

changeOwnerName and changeProjectName shouldn't really be accessible from the outside, which they are right now so the unit tests can import them.

HomePage.react.js eslint errors

eslint current shows the following errors in HomePage.react.js in Atom:

Expected indentation of 2 space characters but found 0.

for lines 13, 14 and 15. Which doesn't make any sense, they aren't indented differently from the rest. If you change it to two spaces, the errors go away, but 4 are needed for it to look the way it should. No idea why that happens...

npm command for running a server that shows the built version

That would be useful for browser testing of the app-to-be-deployed, could also run on 0.0.0.0 so the app can be tested on different devices in the local network.

Is the ServiceWorker Cache Polyfill necessary

See here, I think I might have misunderstood something: https://jakearchibald.com/2014/using-serviceworker-today/

change autoprefixer-core to autoprefixer

You changed it already in the package.json but not yet here:
https://github.com/mxstbr/react-boilerplate/blob/master/makewebpackconfig.js#L90

The old version of the code persists quite long

The old version of the app persists quite long because of AppCache + ServiceWorker. There should be some sort of forced-update mechanism, I have to research that.

Server configs

Lets take some inspiration from html5boilerplate and add more and better server configuration: https://github.com/h5bp/server-configs

Better build/deploy process

Not quite happy with the somewhat hacky build+deploy workflow. Improvement suggestions?

Add .htaccess

It should force a redirect to HTTPS (because of ServiceWorker, which needs HTTPS), and it should route all domain.com/whatever sub pages to the index.html to let react-router take care of them. FIrst implementation:

<ifModule mod_rewrite.c>
  # Make apache follow sym links to files
  Options +FollowSymLinks
  # If somebody opens a folder, hide all files from the resulting folder list
  IndexIgnore */*
  # Enable rewriting
  RewriteEngine On
  # If its not HTTPS
  # RewriteCond %{HTTPS} off
  # Comment out the line above, and uncomment the line below if you're using CloudFlare/... for SSL
  RewriteCond %{HTTP:X-Forwarded-Proto} !https
  # Redirect to the same URL with https://, ignoring all further rules if this one matched
  RewriteRule ^(.*) https://%{HTTP_HOST}/$1 [R,L]
  # If we get to here, it means we are on https:// already
  # If the file with the specified name in the browser doesn't exist
  RewriteCond %{REQUEST_FILENAME} !-f
  # and the directory with the specified name in the browser doesn't exist
  RewriteCond %{REQUEST_FILENAME} !-d
  # and we are not opening index.html (otherwise we get a redirect loop)
  RewriteCond %{REQUEST_FILENAME} !\/$
  # Rewrite all subdomains to the root index.html
  RewriteRule ^(.*) /
</ifModule>

Application Structure

Changing the application structure might be worth thinking about, right now the thing might seem quite bloated and randomly thrown together for newcomers.

Mention Babel in the README

You mention PostCSS, but not Babel. I think these days babel is to JS what postcss is to CSS so you should add minimal doc for Babel :)

Make reducers hot-reloadable

Basically add this: https://stackoverflow.com/questions/34243684/make-redux-reducers-and-other-non-components-hot-loadable/34244419#34244419 (Also see https://github.com/wesbos/Simple-Redux/blob/master/client/store.js)

Cache CSS file with ServiceWorker

Add init script

Add an init script that changes all the names from react-boilerplate everywhere, rm -rf .git, git init etc. Maybe this would be a good starting point: https://github.com/postcss/postcss-plugin-boilerplate/blob/master/start

Fix Open Sans @font-face

Caching on dev server

Is there any way to disable cache on the dev server because none of my changes seem to get loaded, it just loads the cache version instead. Am I just doing something wrong or is the hot loading not working correctly?

serve command should run ngrok

That way you can access your site not only from the local network, but from the entire interweb!

Note: If you submit a PR, do it against the v3.0.0 branch please!

Meteorjs Integration (Feature Request)

Has anyone tried to integrate meteorjs with this one ?

How to make hot reloading work ?

After git clone, npm install and npm start, I edited HomePage.react.js changing Hello World to Hello Redux and saved ! Changes don't propagated to browser even after browser refresh !

Add error routes

E.g. 404, see https://github.com/rackt/react-router/blob/5d5f913d7156f59e3159f366fc6b9f2ac81285f9/examples/master-detail/app.js

Component/Action/Reducer command line generators

https://medium.com/@yamalight/building-modular-javascript-applications-in-es6-with-react-webpack-and-babel-538189cd485f#.ujsh7hpzj

Explain how to contribute

Add a CONTRIBUTE.md file and mention it in the main README, to explain how to contribute to this boilerplate. (I.e. master branch protected, everything runs through PRs to complete travis builds b/c users mainly git clone the master branch to use this boilerplate, which means there can't be any errors in there)

CSS Structure

Thinking of giving the CSS folder structure a slight tweak in v3.0 too. layout and components folder are too similar - when does something become a layout? How big does it have to be?

Maybe take some inspo from http://sassdirector.com/examples/index.html

You may remove NoErrorsPlugin with React Hot Loader 1.3.0

React Hot Loader 1.3.0 fixes a problem that caused NoErrorsPlugin to be necessary. In fact now errors thrown on module level shouldn't prevent future hot reloading of the same file after you fix the problem.

Please update to RHL 1.3.0, and remove NoErrorsPlugin from Webpack configuration.
Thanks!

Move the created history to its own module

Right now you cannot arbitrarily transition to a new page without the Link component from react-router. By having the created history in a seperate module, we can do this:

import history from '../utils/history';

someClickHandler() {
     history.pushState('/');
}

Improve production perf

What about using some babel plugin for the production build, like https://github.com/callemall/material-ui/blob/master/docs/src/.babelrc?

Update boilerplate example

This is more of a Todo so I don't forget it before releasing v3.0.0.

Not doable before everything else is done.

ImmutableJS

I have yet to work with it, so I'm not sure if I should include it. (This redux+immutable.js example looks nice)

It's quite a bit of code overhead just for a warning when you mutate the state directly, which Object.freeze does just the same. Does it have any other benefits?

EDIT: I just realised that the main benefit is that the state is frozen all the way down to every component. This could also be achieved with Object.freeze, by wrapping the returned state in the reducers:

case CHANGE_OWNER_NAME:
      return Object.freeze(assign({}, state, {
        ownerName: action.name
      }));

This won't keep anybody from simply not wrapping it in O.f though. Maybe there's a way to enforce this somewhere later?

Is the webpack config compatible with Windows?

Somebody asked me on Hacker News if the webpack config is compatible with Windows – any Windows users who have tried and for whom it worked/didn't work?

Make components stateless

Remove all classes and make all components pure functions. E.g. turn

class Example extends Component {
    render() {
        return (
            <h1>Hello {this.props.name}!</h1>
        );
    }
}

into

function Example(props) {
    return (
        <h1>Hello {props.name}</h1>
    );
}

Positives

• Performance improvement (src)
• Not possible to use setState(), which is an anti-pattern anyway so we help to keep devs from using it. Since we're using Redux, everything should flow through a reducer.
• Might be better unit testable, have to look into it.

Negatives

• No component lifecycle methods, which might confuse newcomers, so that's another thing we'd have to explain in the docs.

---

Is the more explanation in the documentation worth it? I think so.

Add wrapper component with navigation bar

Similar to https://github.com/mxstbr/login-flow/blob/master/js/app.js#L73-L79

Zombie App

I tested this boilerplate out and subsequently moved on to test out other boilerplates (which also run on localhost:3000). The other apps are not able to be served on localhost:3000 and instead this same app is constantly being served. I could try deleting my browser cache I suppose but have yet to try that. The chrome://appcache-internals doesn't list this app.

Just as surprising is that http://localhost:3000/d37380ea6ac9abdb6c8fd3c00fbaf410.png is still being served (which loads the mxstbr image). This could be a Chrome issue (47.0.2526.106 (64-bit)), I am not sure, I haven't used AppCache before. In Incognito mode, things work as expected -- the image fails to load and if I server something else on 3000 that loads as expected.

How to solve this npm run build error ?

Showing the follwoing error when running npm run build . Please help

ERROR in .//css-loader!.//postcss-loader!./css/main.css
Module build failed: ReferenceError: Promise is not defined
at Object. (F:\My - Worked Projects\My Updated\react-boilerp
late-master\node_modules\postcss-import\index.js:13:27)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.require (module.js:364:17)
at require (module.js:380:17)
at Object.postcss (F:\My - Worked Projects\My Updated\react-boilerplate
-master\makewebpackconfig.js:94:9)
at Object.module.exports (F:\My - Worked Projects\My Updated\react-boil
erplate-master\node_modules\postcss-loader\index.js:28:27)
@ ./css/main.css 4:14-117

ERROR in ./css/main.css
Module build failed: ModuleBuildError: Module build failed: ReferenceError:
Promise is not defined
at Object. (F:\My - Worked Projects\My Updated\react-boilerp
late-master\node_modules\postcss-import\index.js:13:27)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.require (module.js:364:17)
at require (module.js:380:17)
at Object.postcss (F:\My - Worked Projects\My Updated\react-boilerplate
-master\makewebpackconfig.js:94:9)
at Object.module.exports (F:\My - Worked Projects\My Updated\react-boil
erplate-master\node_modules\postcss-loader\index.js:28:27)
at DependenciesBlock.onModuleBuildFailed (F:\My - Worked Projects\My Up
dated\react-boilerplate-master\node_modules\webpack\node_modules\webpack-co
re\lib\NormalModuleMixin.js:315:19)
at nextLoader (F:\My - Worked Projects\My Updated\react-boilerplate-mas
ter\node_modules\webpack\node_modules\webpack-core\lib\NormalModuleMixin.js
:270:31)
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\node_modules\webpack-core\lib\NormalModuleMixin.js:292:15
at runSyncOrAsync (F:\My - Worked Projects\My Updated\react-boilerplate
-master\node_modules\webpack\node_modules\webpack-core\lib\NormalModuleMixi
n.js:173:4)
at nextLoader (F:\My - Worked Projects\My Updated\react-boilerplate-mas
ter\node_modules\webpack\node_modules\webpack-core\lib\NormalModuleMixin.js
:290:3)
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\node_modules\webpack-core\lib\NormalModuleMixin.js:259:5
at Storage.provide (F:\My - Worked Projects\My Updated\react-boilerplat
e-master\node_modules\webpack\node_modules\enhanced-resolve\lib\CachedInput
FileSystem.js:52:20)
at CachedInputFileSystem.readFile (F:\My - Worked Projects\My Updated\r
eact-boilerplate-master\node_modules\webpack\node_modules\enhanced-resolve
lib\CachedInputFileSystem.js:140:24)
at DependenciesBlock.onLoadPitchDone (F:\My - Worked Projects\My Update
d\react-boilerplate-master\node_modules\webpack\node_modules\webpack-core\l
ib\NormalModuleMixin.js:255:7)
at DependenciesBlock.loadPitch (F:\My - Worked Projects\My Updated\reac
t-boilerplate-master\node_modules\webpack\node_modules\webpack-core\lib\Nor
malModuleMixin.js:182:27)
at DependenciesBlock.loadPitch (F:\My - Worked Projects\My Updated\reac
t-boilerplate-master\node_modules\webpack\node_modules\webpack-core\lib\Nor
malModuleMixin.js:186:21)
at DependenciesBlock.loadPitch (F:\My - Worked Projects\My Updated\reac
t-boilerplate-master\node_modules\webpack\node_modules\webpack-core\lib\Nor
malModuleMixin.js:223:61)
at DependenciesBlock.loadPitch (F:\My - Worked Projects\My Updated\reac
t-boilerplate-master\node_modules\webpack\node_modules\webpack-core\lib\Nor
malModuleMixin.js:186:21)
at DependenciesBlock.loadPitch (F:\My - Worked Projects\My Updated\reac
t-boilerplate-master\node_modules\webpack\node_modules\webpack-core\lib\Nor
malModuleMixin.js:223:61)
at DependenciesBlock.doBuild (F:\My - Worked Projects\My Updated\react-
boilerplate-master\node_modules\webpack\node_modules\webpack-core\lib\Norma
lModuleMixin.js:241:4)
at DependenciesBlock.build (F:\My - Worked Projects\My Updated\react-bo
ilerplate-master\node_modules\webpack\lib\NormalModule.js:84:14)
at Compilation.buildModule (F:\My - Worked Projects\My Updated\react-bo
ilerplate-master\node_modules\webpack\lib\Compilation.js:126:9)
at Compilation. (F:\My - Worked Projects\My Updated\react-bo
ilerplate-master\node_modules\webpack\lib\Compilation.js:398:8)
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\lib\NormalModuleFactory.js:58:13
at NormalModuleFactory.applyPluginsAsyncWaterfall (F:\My - Worked Proje
cts\My Updated\react-boilerplate-master\node_modules\webpack\node_modules\t
apable\lib\Tapable.js:75:69)
at onDoneResolving (F:\My - Worked Projects\My Updated\react-boilerplat
e-master\node_modules\webpack\lib\NormalModuleFactory.js:38:11)
at onDoneResolving (F:\My - Worked Projects\My Updated\react-boilerplat
e-master\node_modules\webpack\lib\NormalModuleFactory.js:121:6)
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\lib\NormalModuleFactory.js:98:13
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\node_modules\async\lib\async.js:721:13
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\node_modules\async\lib\async.js:52:16
at async.forEachOf.async.eachOf (F:\My - Worked Projects\My Updated\rea
ct-boilerplate-master\node_modules\webpack\node_modules\async\lib\async.js:
236:30)
at _parallel (F:\My - Worked Projects\My Updated\react-boilerplate-mast
er\node_modules\webpack\node_modules\async\lib\async.js:712:9)
at Object.async.parallel (F:\My - Worked Projects\My Updated\react-boil
erplate-master\node_modules\webpack\node_modules\async\lib\async.js:726:9)
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\lib\NormalModuleFactory.js:75:10
at F:\My - Worked Projects\My Updated\react-boilerplate-master\node_mod
ules\webpack\lib\NormalModuleFactory.js:28:4
Child extract-text-webpack-plugin:
+ 1 hidden modules

ERROR in ./~/css-loader!./~/postcss-loader!./css/main.css
Module build failed: ReferenceError: Promise is not defined
    at Object.<anonymous> (F:\My - Worked Projects\My Updated\react-boi

lerplate-master\node_modules\postcss-import\index.js:13:27)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.require (module.js:364:17)
at require (module.js:380:17)
at Object.postcss (F:\My - Worked Projects\My Updated\react-boilerp
late-master\makewebpackconfig.js:94:9)
at Object.module.exports (F:\My - Worked Projects\My Updated\react-
boilerplate-master\node_modules\postcss-loader\index.js:28:27)

Migrate to Babel 6

Remove react/lib/assign from reducer.js

Add npm run pagespeed command

Add npm run pagespeed command to check page speed, maybe using https://github.com/addyosmani/psi

Add ?branch=master to Travis status image link

I.e. change the img link in the README to https://travis-ci.org/mxstbr/react-boilerplate.svg?branch=master

Images in HTML files are not moved to the build folder

Images in the HTML do not get moved to the build folder.

See jantimon/html-webpack-plugin#82

Integrating redux-simple-router

https://github.com/jlongster/redux-simple-router

Find and remove all eslint errors

There are a lot of eslint errors all around, should find and remove them.

Better documentation

• Files
• Explanation of the possible npm commands
• Testing
  • How to write unit tests
    • Mocha
    • expect
    • Real world usage
      • Reducers
      • rewire
      • Actions
  • How to write good unit tests (see this article and this response for inspo)
  • How to write component tests
    • Shallow rendering
    • enzyme
  • Browser testing
    • npm run serve
• Explanation of the main design decisions behind this boilerplate (maybe incomplete)
  • User side
    • JS
      • ESNext Features (see #165)
      • ImmutableJS
      • React
        • react-router
        • Components/Containers split (see #33, this article)
        • Redux
          • reselect (see #61)
          • redux-simple-router
          • redux-saga
      • eslint
        • Airbnb style
      • FontFaceObserver
    • CSS
      • CSS Modules
      • sanitize.css
      • PostCSS
        • cssnext
        • autoprefixer
        • postcss-focus
        • cssnano
    • Offline First
      • ServiceWorker
      • AppCache
  • Developer side
    • Webpack
    • Babel
    • Beginner
      • Modules (export and import)
      • Prerequisites
        • node
          • npm
        • git
• FAQs
  • nodejs-legacy for linux (see here)
  • Error: listen EADDRINUSE 127.0.0.1:3000
  • Hot-reloading doesn't work?
  • Why do I need this?
  • Can I use Sass with this?
  • I don't want to use Redux!
• Gotchas
  • Images in the HTML file (Copy and past from README)
• Advanced Patterns
  • Ducks (see #27)
  • ryanflorences non-flat app structure (see #27)
• Deployment guides
  • scp
  • Heroku
  • Codeship
  • Beanstalk

Legend: Cursive todos are nice-to-haves, but only to be done when everything else is done, and bold todos are must-haves before releasing

Note: If you're planning on writing one of these sections, please be sure to talk about the v3.0.0 branch and to submit your PR against the v3.0.0 branch!

Change .react.js extension

See #27 (comment), maybe consider switching to .jsx for react files?

Going to look around at different boilerplate to see what the current consensus is.

Add the stylesheet to the index.html on build automatically

Right now, before deploying you have to add this line to the index.html:

<link rel="stylesheet" href="css/main.css">

That should be done automatically.

Name/Logo/Website

Thinking about taking on a better name/adding a logo/making a website with collected documentation. Not sure the project is mature enough just yet, but it's on my roadmap. Any input appreciated!

@import with globbing in main.css

In the main.css file, replace all @imports with many less using globbing https://twitter.com/_DECAF/status/677576211518894080?s=09

Add PREREQUISITES.md

Add PREREQUISITES.md for complete beginners, which explains/links to guide that explain how to install and use node, npm, git,...

Fix unit tests

I forgot to fix the unit tests when I changed the application structure

Remove `&&` from build/start commands

They aren't necessary between setting the NODE_ENV variable and the actual commands

Use babel hmre preset for hot loading and error catching

Less boilerplate, more good stuff :)

https://github.com/danmartinez101/babel-preset-react-hmre