Using Laravel Mix in a WordPress Theme

If you've ever tried installing Webpack and configuring it from scratch, you know how hard it is. After working with Laravel and using Laravel Mix, I wanted to use it in every PHP based project. Luckily you can!

What Laravel Mix does is take the pain out of configuring Webpack and provides you with an easily chainable set of build tools. Using these tools you can easily compile your CSS and Javascript assets to help create a modern work flow! I was inspired by Eric Barnes article, but deviated a little bit so we could use other frameworks such as TailwindCSS.

Pre-Requisite

All you have to have as a pre-requisite to this tutorial is an NPM package configured for your WordPress theme. If you are using Underscores.me boilerplate theme, you are ready to go!

Step 1: Install Larvel Mix

All you have to do to install Laravel Mix is run the following command:

npm install laravel-mix --save-dev

Now we have Laravel Mix installed as a development dependency within our theme! It's important to have this as a development dependency since there is no point to having this in our production release. It literally builds our assets for production!

Step 2: Install cross-env

The newest version of Laravel Mix requires the cross-env library to be installed as well. To install this library, run the following command:

npm install cross-env --save-dev

That is really the only dependency we need to have Laravel Mix up and running. Let's add a few scripts that compile our assets and add an entry point for Laravel Mix to get started and we are good to go!

Step 3: Add Build Scripts to Package

When compiling your assets, you need to define which commands to run. These commands live under the scripts key in your package.json file. Depending on your set up, you might have some scripts in there by default. I know in some customizations of the Underscores theme, it ships with some build scripts for WordPress. Anyways, you need to add the following build scripts to your scripts key in the package.json file:

...
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": "npm run development -- --watch",
    "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 --no-progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"
}
...

There are quite a few scripts in there! If you haven't worked with Laravel Mix before, they may be new. Let's break down the 3 we use all the time.

First, we have the dev script. This script is run using the following command:

npm run dev

What this does is compile all of our assets in development mode. This is an important distinction instead of production mode. Reason being is that the resources aren't minified or compressed when compiled so debugging is easier. You only want to run this when you are developing.

The next script is my favorite script. It's the watch command:

npm run watch

What this command does is watches your build hierarchy. When a change occurs, it automatically re-compiles your assets in development mode. This is extremely convenient so all you have to do is just re-fresh your page and the new version of you compiled assets are ready for your use!

Just make sure you kill this command before you close your editor or it will keep running!

The final script I use often is the production script:

npm run production

If you have a CI process in place for your theme, make sure you have it build and compile your assets with the production script. This will minify and lint your files for production ready use.

Step 4: Add Entry Point for Compilation

The final step is to add the webpack.mix.js file to the root of your theme directory. This is the entry point for when you wish to compile assets. All of your Laravel Mix configuration will take place in this file. If you are using VueJS, TailwindCSS, Bootstrap, SCSS, anything that needs compiled, the configuration will live in this file.

Since we aren't setting up any of these in this tutorial, just add the following code to this file:

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

Now we have the mix object at our disposal and we can begin to chain our build commands! If you want to set up TailwindCSS right away, check out the article for Installing TailwindCSS in a WordPress Theme.

Of course, if any questions come up, feel free to shoot me a question on Twitter (@danpastori) or post in our community so others can benefit from your question as well!