WordPress development with Webpack, Babel and Browsersync

Overview

Task runners can enhance WordPress development by automating tasks such as SASS compilation, minification and JavaScript transpiling. The following configuration seeks to take advantage of this tooling in development projects that use a web server such as Apache or nginx.

I use an example of WordPress theme development. However, this configuration can be applied to any project where the local development environment is served via a local web server.

In particular, I use this configuration to have the following happen automatically when I save a file in my project:

Hot browser reloading. No need to hit refresh.
SCSS transformed to CSS.
JavaScript transpiled to vanilla JavaScript. Enables us to use the latest JavaScript standards which is then converted to ES5 (high browser compatibility) JavaScript.

Prerequisites

The following are beyond the scope of this article.

An existing WordPress development environment (local server stack/virtualized environment). e.g. A local WordPress installation served from https://mysite.dev.
Node.js.

Process

File structure

Following is an example of a WordPress child theme file structure containing the bare minimum of a functions.php and a style.css file. In the following steps, we’ll make a few additions.

js/
 bundle.js
src/
 scss/
  style.scss
 index.js
functions.php
package.json
style.css
webpack.config.js

In this file structure, src is as a directory that will contain files that Webpack will process. For example, Webpack will:

Write to style.css from src/scss/style.scss.
Write to js/bundle.js from src/index.js.

Generate package.json

Run the following command to initiate your project as an npm repository and as a result, create your package.json file.

npm init

npm will ask you a series of questions to populate your package.json file. Some suggested responses:

name: <The slug of your WordPress theme/project>
version: 1.0.0 (as suggested).
main: src/index.js

Install development dependencies

In one go

npm install babel-core babel-loader babel-preset-env browser-sync browser-sync-webpack-plugin css-loader extract-text-webpack-plugin node-sass sass-loader webpack --save-dev

Note on the Extract Text Webpack Plugin

At the time of writing, the release version of the Extract Text Webpack Plugin (3.0.2) wasn’t compatible with the latest version of Webpack (4.13.0). The following command was required to install an alpha version that is compatible.

npm install -D extract-text-webpack-plugin@next

For more information, see Webpack 4 compatibility (#701) – Extract Text Webpack Plugin.

Individually

Install your task runner. In this example, I am using Webpack.

npm install webpack --save-dev

For hot reloading, install BrowserSync. For convenience, we will also install the BrowserSync plugin for Webpack so that we can configure BrowserSync in our Webpack configuration.

npm install browser-sync browser-sync-webpack-plugin --save-dev

If you are using SASS, install the required modules for Webpack to process your SASS into CSS. Note that I have included the Extract Text Plugin which I can use to instruct Webpack to write to our style.css file.

npm install css-loader extract-text-webpack-plugin node-sass sass-loader --save-dev

Finally, if we are including JavaScript in our project, we may wish to include Babel, and babel-preset-env. This is optional, and allows us to write ES2015+ JavaScript and have it transformed to regular JavaScript in our project.

npm install babel-core babel-loader babel-preset-env --save-dev

Create and edit webpack.config.js

Some remarks about the configuration:

entry: Use the index.js file in the src folder of our project to find the location of SCSS files and to discover any JavaScript to process.
output: Write transpiled JavaScript to js/bundle.js.
module|rules/plugins: Use appropriate loaders with the Extract Text Plugin to write CSS to the style.css file.
module|loaders: Use Babel to compile JavaScript down to ES5 standard (high browser compatibility).
plugins: When we run Webpack in –watch mode, start BrowserSync proxied to our local development address and have BrowserSync watch for file changes in the project folder.

src/index.js

require('./scss/style.scss');

package.json

Include a build and a serve script. The serve script will watch for changes and rebuild.

"scripts": {
  "build": "webpack",
  "serve": "webpack --watch"
},

Build or serve!

Run npm run serve so load Browsersync and have it automatically recompile and reload changes when you make modifications to your PHP code and JavaScript/SASS source.

Steven Thompson