A beginner’s guide to build a new SPA with ES6, SCSS, React, Webpack and HMR.


After having been working on a project which used ReactJS to build several SPAs (Single Page Applications).

I’ll openly admit it was a pain for me to get working even a basic project or starter template. The reason is because there are lots of new concepts, frameworks and technologies. I decided to write down some clarifications, notes, learning techniques and starter template which I did in the process to understand all this front end stack.

The reason for doing other React starter template for single page applications (SPA) is because when I started to look into templates it took to me hours and hours of googling and testing different templates to have some starting point for my SPA application.

There are templates with hundreds of dependencies. Why not reduce to the minimal needed to start playing with React?

Let’s try! Let´s describe the main components to configure in our project:

  • Development Server
  • JavaScript and Frameworks
  • Package Manager
  • Build System - Bundler
  • Browser Sync, Live Reload and HMR (Hot Module Replacement)
  • Styling  

Development Server

As we pretend to do Web Development could be ideal to configure some web server locally for faster developing.

What web server should we use? IIS Express? Tomcat? Node Server?… We don´t want a full-featured Web Server for our dev local machine, what we want is more integration with tooling, plugins, transpilers, etc. So instead of using Web Server, we will use a Dev Server. Normally, using React + ES6 + Webpack we should a Node.js server.

express vs webpack-dev-server

  • Express is a Node.js server. If you want advanced configuration you can use Express directly + configure yourself the integration with webpack.
  • Webpack-dev-server is a Node.js Express server, which uses webpack-dev-middleware under the hood, which provides fast in-memory access to the webpack assets to generate the webpack bundle.

webpack-dev-server vs webpack-dev-middleware

  • webpack-dev-server provides you with a Node.js Express server + WebPack Integration + Live Reloading
  • webpack-dev-middleware is kind of webpack connector for dev servers. This can be useful if you already have a Node.js server or if you want to have full control over the server.
  • NOTE: You should use webpack-dev-server strictly for development. If you want to host your application, consider other standard solutions, such as IIS, Apache or Nginx.

_I decided to start using _webpack-dev-server_ initially as it is _easy to configure_ and require less dependencies._


JavaScript and Frameworks

Nowadays, there are lot of languages and frameworks to do Modern Web Development. This is again, a swamp of doubts for beginners… Eventually, which will be generated is plain JavaScript + CSS + HTML because what browsers understands. But using some modern web intermediate languages and frameworks will make our life easier. This post is not about which language is the best to use, everyone has his own opinion… Depending on the language and frameworks we use we should be configuring our development environment in a different way.

_I decided to use _ES6_ compiled with _Babel_ + _React. For the starter template is enough, later we can add more external JS libraries if required.


Package Manager

NPM is the most used package manager for JavaScript.

There is a new tool called yarn, which is a dependency management tool. Just to avoid confusions, yarn is not a replacement for NPM registry. Yarn is a client tool which allows us to manage Deterministic dependencies — with yarn.lock, you’ll get the same versions of the same packages installed in the same directory structure every time. That will save a lots of development efforts and frustrations.

I decided to use yarn as a client tool for package management instead of using npm install, I will use yarn.  

Build System - Bundler

Building large scale JavaScript applications requires functional programming and apply “divide and conquer”. In the same way we use classes using different files when programming on C#, we use Modules in JavaScript. Historically were introduced different Module Formats (AMD, CommonJS, UMD, …) and Module Loaders (RequireJS, SystemJS, …) where Module Format means syntax and Module Loader means execution or implementation. There are lots of JS projects developed using different approaches. Even ES2015 (ES6) has its own module format. Anyways, this post isn´t about modules in JS, so let´s say that we have two different approaches to load modules to the browsers:

  • Module Loaders. Load the required JS Modules as a different files using JavaScript at execution time.
  • Bundlers. Package all the solution in one bundle.js file which contains all your application modules.
    • Browserify, WebPack, …

_I decided to use the build system / bundler called _WebPack_ because it has some good features like: _

  • _Bundles AMD, CommonJS and ES2015 modules _
  • Code splitting
  • _Bundles more than just a JavaScript modules (CSS, images, …) _
  • _Uses loaders for transformation before bundling _
    • ES2015, SCSS, …


Browser Sync, Live Reload and HMR (Hot Module Replacement)

One of the coolest features in Web Development is live reload which means that every time you save your source files, the changes will be automatically reflected in the browser, and that means quick and fast development flow.

Live Reloading vs Hot Module Replacement

  • Live Reloading. Provides a way to refresh browser when a source file has been changed.
  • Hot Module Replacement. This is a further step. It provides a way to patch the browser state without a full refresh. It is particularly powerful with technology such as React, because allows for page refreshes without losing state, So, if you have navigated through several pages and filled out several forms to arrive at a corner of your application where you’d like to test a bug, making a change in your application triggers an instant page refresh, while maintaining that state.
    • Note: An IDE feature known as safe write can break hot loading. Please turn it off when using HMR.

Which HMR do we need?

Just to be clear, what we need is a Hot Module Replacement (HMR) that integrates perfectly with WebPack and React. After googling a lot, there are different options to configure it:

  • Using react-transform-hmr. This blog post explains all the concepts really well and how to configure it. (it didn´t work for me).
  • Using react-hot-loader

_I decided to use _React Hot Loader 3_ integrated with WebPack as a HMR._



There are three main CSS pre-processors: Stylus, LESS and SASS. SASS is a great option as it’s widely adopted and there are tons of mixins and tool sets available in the community.

SASS integration with WebPack

We could use SASS directly using node-ssas tool which allows us to pre-process all .scss files and their @imports. An example of use here:

node -i node-sass -g
node-sass app/stylesheets/main.scss > dist/stylesheets/main.css

But ideally we should integrate SASS in webpack and HMR workflow. For development environment it’s recommended NOT to separate the output CSS file from the bundle.js. As webpack is able to use the same bundle.js file for css as well and inject the CSS properly by using JS. Doing that, will be easier the HMR configuration for SASS (SCSS files). For production environment, we will need to publish the final CSS final as a separate file and we could use the plugin extract-text-webpack-plugin to achieve it.

_I decided to use SASS and follow directives of The _7-1 Pattern_ using this _blog post_ as a reference._



Things To include in the template

There is a bunch of things I’d like to include in the starter template like:


Minimal Starter Template

You can see and download the minimal starter template on Github: https://github.com/jquintozamora/react-es6-webpack-minimal-starter-template


More Starter Templates

There we have more well tested starter templates (more complex as well) as a reference:



Author: José Quinto
Link: https://blog.josequinto.com/2016/11/14/how-to-build-a-new-spa-with-es6-scss-react-webpack-and-hmr-the-beginners-guide/
Copyright Notice: All articles in this blog are licensed under CC BY-SA 4.0 unless stating additionally.