Who's this for

  • Newer WordPress developers and folks that go cross-eyed reading Gulp's syntax.

tl;dr

  • Elixir was built as a Laravel asset manager, but with some simple configuration, you can drop it into any project.
  • In addition to web apps, Elixir's plug-and-play nature makes it a great candidate for any WordPress/CMS project.

Out of the box, Elixir makes certain, Laravel-based assumptions about how you're mananging your assets: everything lives within a resources/assets directory, and compiles to a public directory. For Laravel projects, this is as close to plug-and-play as you can get, but if you want to use it within another framework, it's not quite so convenient.

Elixir has a variety of configuration options—some of which you will need to do some light source-diving to discover. There are two, in particular, that will help us solve the problem above:

elixir.config.assetsPath

This option allows you to override that default resources/assets path and define your own file path to your assets. At the top of your gulpfile.js file, include the following:


elixir.config.assetsPath = 'path/to/assets/'; // Don't forget your trailing slash!

Note that this is a global option, so whatever directory you define has to include both your styles and your scripts.

elixir.config.publicPath

This variable allow us to define where we output our compiled files. As the name suggests, it will assume a path of public/ by default, but we can easily override that. In your gulpfile.js file, include the following:


elixir.config.publicPath = 'path/to/assets/'; // Don't forget your trailing slash!

Unlike assetsPath, Elixir allows also allows us to define outputs on a per-task basis by passing a second argument into its sass, less, and scripts methods:


elixir(function(mix) {
    mix.sass('style.scss', 'min/style.min.css'); 
});

elixir(function(mix) {
    mix.scripts('app.js', 'min/app.min.js'); 
});

If those functions make you question the universe, fear not. We'll jump into more detail soon.

Using Elixir in WordPress

To put this configurability into a real-word scenario, let's install Elixir into a WordPress theme.

1. Create a package.json file

If you don't already have one, create a new file in the root of your theme, name it package.json, and copy the following:


{
    "name": "your-theme-name",  // Required
    "version": "1.0.0", // Required
    "private": true // Prevents accidental publication of private repos
    "dependencies": {
        "laravel-elixir": "^5.0.0" // Install the newest version of Elixir
    },
    "devDependencies": {
        "gulp": "^3.9.1" // Since Elixir is built on top of Gulp, we'll need to install it, too.
    }
}

2. Install Gulp and Elixir

In the terminal, navigate to your theme directory. The specific commands will vary based on your individual environment, but if you're running WordPress in MAMP, you will likely need to run something like:


$ cd ../..
$ cd Applications/MAMP/htdocs/your-wordpress-root/wp-content/themes/your-theme

Once in your theme, you will need to check to see if you have Gulp installed globally:


$ gulp -v

If the terminal returns a version number, you're set. IF not, you will need to install Gulp as a global NPM package:


$ npm install --global gulp

Finally, install the rest of the dependencies—including Elixir—as they were defined in your package.json file:


$ npm install

This last command may take a few seconds, and could result in some gnarly-looking output about dependencies and deprecations. Ignore it. If NPM encounters a true error, it will exit out of the process entirely and let you know.

Once NPM has finished running, you will see a new directory within your theme called node_modules, which contains the packages and dependencies that you just installed. If this is your first time working with Gulp, I encourage you to click through the directory, if only to check out the sheer volume of code that NPM just handled for you.

Note: if you're using version control (and you are, right?), you will likely want to add the node_modules folder to your .gitginore file.

As with every other thing on the Internet, there are arguments for and against (for an excellent synopsis of both sides, check out Addy Osmani's Checking in front-end dependencies). For our WordPress usecase, though, we won't need NPM on our production server, so we can keep things simple and exclude it.

3. Create Your Gulpfile

The gulpfile dictates the specific actions, called "tasks", that Gulp will perform when you run it. These tasks could include concatenating different files, compressing your CSS, minifying your JS, or optimizing your images. Each one of those tasks is crucial for a speedy site, but today, we're going to focus only on Javascript and CSS.

In your theme directory, create a file called gulpfile.js, and copy the following:


var elixir = require('laravel-elixir'); // Require Elixier
elixir.config.assetsPath = 'assets/'; // As we said above, make sure this points to the directory within your theme that stores your assets. Also be sure to include the trailing slash.

// Terminal Commands
// To run all tasks one time: gulp
// To have Gulp run when it detects changes in relevant files: gulp watch
// To have Gulp compress/minify your output for production: gulp --production

// Task #1: Using Sass's @import syntax, Elixir will compile your imports into a single file before compress. Don't forget that all paths are relative to your assetsPath configuration above.
elixir(function(mix) {
    mix.sass('/path/to/your-styles.scss', '/path/to/your-styles.min.css');
});

// Task #2: Compile each JS file defined here into a single file.
elixir(function(mix) {
    mix.scripts([
    'path-to-js/script1.js',
     'path-to-js/script2.js',
     'path-to-js/script3.js',
    ], 'site.min.js')
});

Elixir handles a variety of other use cases, too: tasks for LESS, vanilla CSS, and CoffeeScript are all readily available. It also ships with Babel, Browserify, and Browsersync, and can handle tasks like generating source maps, copying files and directories, and versioning your files. In a recent episode of the Laravel Podcast, Jeffrey also indicated that the next major release of Elixir will also migrate to Webpack.

The Elixir documentation is excellent, and if any of the above appeals to you, you will find answers quickly. But, if none of that makes any sense, don't worry. Our focus is on basic WordPress theme development, and if you stick to compiling and compressing your assets, your work will still be worlds quicker than most themes out there.

5. Run Elixir

Once your gulpfile.js is saved, we can put Elixir to work. Back in your terminal, navigate to your theme directory, and run the command gulp. As Gulp processes the tasks you've defined, it will display its progress in the terminal window. If all goes smoothly, Elixir will display a nice desktop notification that your tasks were successful. If not...

6. Handling Errors

Elixir will also let you know if some aspects of your task has failed. Tasks can fail for any number of reasons, but in our example, failures will likely come in two forms:

  1. There is a syntax error that keeps your styles or scripts from compiling. If that's the case, look at your terminal output: it will tell you the file and line number where it encountered the error. When I hit this error, it's often something silly like a missed semicolon or a misspelled variable. Take a look at the file in question and see what you can find.

  2. Elixir can't find an asset you referenced in your gulpfile.js. In these cases, Elixir will highlight the file it can't find, and actually highlight the filepath it followed to find it. Check that file path, and make sure it matches the structure of your theme. You may need to adjust your assetPath configuration, or a filepath within an individual task.

If you're dropping Elixir into an existing project, it can take a few minutes to untangle errors that might arise. Don't get discouraged: Elixir's terminal output will tell you what you need to know to get it solved.


So, how'd I do? This is my first post on this blog, and one of my first pieces of public technical writing, so I am completely open to feedback. Yell at me on Twitter if you have ideas on how I could improve this type of post.