WebPack HMR and WordPress A Beautiful Union

access_timeApril 27, 2016


How to setup a WordPress theme development environment that leverages WebPack’s HotModuleReplacement for style sheets, JavaScript, and even live html injection.

This setup will use our bundler to manage front-end assets,  BrowserSync to proxy our local WordPress install, and a set of clever file watchers and middleware to get an HMR-style-update-with-no-reload-effect on PHP updates.

In this post, I will highlight the key pieces; see this sample repo for an example.


In order for this to work, here’s what needs to happen:

  • BrowserSync Duties
    • Serve a proxy or your local WordPress install.
    • Inject JS & CSS HMR updates via middleware.
    • Inject HTML changes when your PHP files change via plugin.
  • File Watchers Duties
    • Watch any file not covered by WebPack (not js, not css, etc).
    • On file changes, synchronize assets from the SOURCE folder to the DIST folder.
    • On file changes, trigger BrowserSync’s HTML injector.
    • The file watcher provider options include: BrowserSync’s built-in file watchers OR any other file watching tool. For example, this could be part of a Gulp build process.
  • WebPack Duties
    • All standard duties, including bundling and optimizing front-end assets.
    • On file changes, send HMR updates to BrowserSync’s middleware.

WebPack Setup

This is an example of how to fulfill those duties. For a minimal, working example see this sample repository.


  • As a matter or re emphasis: make sure your dev build is creating a 'styles.css' file; this is the only required file by WordPress’ API.
    In early versions of my build process, I left a blank 'style.css' file in my ‘src’ directory and let the file watchers copy it over — knowing that WebPack would replace it.

BrowserSync Setup

Actual example.

Using this format, you would run your build with node start.js. Or setup a script in package.json:

In this case, npm start.


With this setup you can use WebPack for theme development with all the glory of HMR! Wonderful!

For my own next steps, I’ve since discovered tools such as roots.io and I’m interested in seeing if these tools can improve my workflow.  They certainly seem in the right direction.

Further Reading

Learn more about WebPack from SurviveJS. Right now, this is definitively the best resource on the internet to learn the ins and outs of this beastly bundler.