Using Laravel Mix for Your WordPress Theme

Laravel Mix is a fluent wrapper around the webpack module bundler, and it provides common tools that help you compile CSS and JavaScript. It’s easy to work with, and although it comes baked into the Laravel framework, you can use it anywhere.

This site is using WordPress, and when I created the theme I used Mix to handle the asset compiling; it was simple to setup. Here is a quick overview of how I did it in four steps. Please note, you will need to have a recent version of Node and npm installed on your machine before continuing.

Step 1. Create the package.json File

The package.json file is required to get all the Node modules you’ll need. Create this package.json file in your theme’s directory and add the following to it:

{
  "private": true,
  "scripts": {
    "dev": "npm run development",
    "development": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
    "watch": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --watch --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
    "watch-poll": "npm run watch -- --watch-poll",
    "hot": "cross-env NODE_ENV=development node_modules/webpack-dev-server/bin/webpack-dev-server.js --inline --hot --config=node_modules/laravel-mix/setup/webpack.config.js",
    "prod": "npm run production",
    "production": "cross-env NODE_ENV=production node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"
  },
  "devDependencies": {
    "laravel-mix": "0.*"
  }
}

I pulled these from the Laravel repo and removed all the devDependencies except for laravel-mix.

From your terminal, run npm install and all the dependencies will be pulled down automatically.

For my theme, I decided to utilize Bootstrap, so I required it via the command line:

npm install bootstrap-sass --save-dev

Bootstrap also requires jQuery so pull it in:

npm install jquery --save-dev

Now it has all the dependencies, and we are ready to setup the webpack file.

Step 2. Webpack Mix

Next up, create a file webpack.mix.js in the same directory as your package.json and add the following:

const { mix } = require('laravel-mix');

mix.js('js/app.js', './')
   .sass('sass/style.scss', './');

What this is doing is first loading the laravel-mix Node module, then setting up the compile steps. One for the JavaScript and another for Sass.

The important part here is the paths in the second param. For example, WordPress expects a style.css file in the root of your theme and by specifying the path as ./, it’s telling Mix to save the compiled file to the correct location.

Step 3. Create Your style.scss File

The final step is to create your style.scss file and based on the paths above this will need to go here sass/style.scss. Create this file and add the following:

/*!
Theme Name:         dotdev 2017
Theme URI:          https://dotdev.co
Description:        Minimal theme based on nosidebar
Version:            1.0.0
Author:             Eric L. Barnes
Author URI:         https://dotdev.co/
Text Domain:        dotdev-2017

License:            MIT License
License URI:        http://opensource.org/licenses/MIT
*/

// Bootstrap
@import "node_modules/bootstrap-sass/assets/stylesheets/bootstrap";

Please note the heading section has a special comment. By opening the multiline comment with /*! this tells the Sass compiler the comment should be kept in the source even after compiling. WordPress uses this in your wp-admin themes section.

Finally, we import the Bootstrap styles from the node_modules directory, and everything should be set and ready to go. If you run npm run dev this should output a style.css with Bootstrap included.

Of course, you are free to add any additional Sass files you need for your theme, here are mine:

// Variables
@import "variables";

// Bootstrap
@import "node_modules/bootstrap-sass/assets/stylesheets/bootstrap";

@import "site/layout";
@import "site/home";
@import "site/sidebar";
@import "site/author";
@import "modules/post";
@import "media/media";

Step 4. Create an app.js

Now, to compile your Bootstrap JavaScript create a new file js/app.js and import Bootstrap:

require('bootstrap-sass');

Save this, and run npm run dev again. Now you should have a compiled app.js file in your theme root with all the Bootstrap JavaScript.

That is all that is required. After this, you’ll just want to get comfortable with the Laravel Mix commands.

Laravel Mix Commands

Laravel Mix provides a few helpful commands while you are developing your theme. Here is an outline for the main ones you will need:

npm run dev

Run dev compiles the assets but does not minify. Useful for seeing the full source.

npm run production

Run production compiles and minifies, ready for you to push to production.

npm run watch

This keeps a watch on your files and if any change, then it runs the dev command automatically.


Check the Laravel Mix documentation for a complete list of everything it can do. Pretty much everything is supported when you are using it outside of Laravel, except for the versioning which relies on an internal Laravel helper function.

I hope this helps you create your next WordPress theme.