Grunt is a NodeJS-powered, automated JavaScript task runner that can be used to take a lot of the repetitive work out of web development.
In this article, I will give an introduction to Grunt and the technologies it works with, as well as go over some of the ways it can be used to improve WordPress development. I will also recommend some tools to get you up and running with Grunt for plugin and theme development, and generating full WordPress sites.
In a future article, I will cover how to automate the process of preparing a plugin for release on WordPress.org or through other means.
What you need to know about Grunt, Node, and NPM
As I said above, Grunt is powered by Node. Node is a JavaScript runtime that allows you to run JavaScript server-side, and is used to build desktop, mobile, and web-applications. In a previous article for Torque, I discussed how to use Node to build a single-page web app, using WordPress as the backend.
When using Grunt, you don’t need to know very much about Node, other than how to install it — which is actually quite simple — and the role of the Node Package Manager (NPM), a dependency manager for Node packages. If you use Composer, it will be very familiar to you, as Composer is, in many ways, modeled after NPM.
When using Grunt, our dependencies are Node Modules that handle the various task, such as SASS/LESS compiling or JavaScript linting and minification. Using a dependency manager makes the actual code that handles these transparent. NPM pulls in the modules you need for a task, and any modules that those modules need automatically for you.
Installing Node, Grunt, and NPM
If you do not already have Node installed in your development environment, then that is the first step. On a Mac or Windows computer, you can download an installer at: http://nodejs.org/download/
There is also a more exhaustive list of installation methods, which includes how to install using a Linux package manager: https://github.com/joyent/node/wiki/installing-node.js-via-package-manager
Since NPM is now included in the download of Node, it does not need to be installed separately. Now all that is left to do is install Grunt. The easiest way to install Grunt is using NPM itself. To install Grunt system-wide, so it is available for all projects, simply open up your terminal and type:
npm install -g grunt-cli
In my experience on Mac and Ubuntu, it is necessary to use sudo when installing grunt-cli.
Grunt templates & Grunt init
In the following sections, I’m going to show you tools that use Grunt to automatically create a WordPress theme, plugin, or full-site. These projects have a simple installer that prompts you for details and configures your projects automatically. These prompts are used for things like project name and function prefixes.
In order for these time-saving starter projects to be available to you, you must have grunt-init installed.
Normally we use Grunt to manage installation of Node Modules, and have them installed in the project itself. But, grunt-init — the module that powers these types of projects — is better when installed globally, and therefore needs to be installed separately.
Again, NPM makes this easy:
npm install -g grunt-init
Now you can install Template type projects, like the ones discussed below, in a subfolder of your user directory called .grunt-init.
WordPress theme & plugin theme starter with Grunt
The good people at 10up have open-sourced their starter theme and starter plugin projects, which use Grunt both for project generation and for automating development processes. These projects use grunt-init for creating new themes or plugins, and apply global settings, such as function prefixing and project naming, using a few simple prompts.
The automated setup is a nice time saver, and a great way to ensure consistency throughout your projects. They also include everything you need for automating your JS and CSS development, including packaging the plugin or theme for release.
Installing and running these templates is easy. To install the plugin template simply clone the repository to your .grunt-init directory like this:
git clone https://github.com/10up/grunt-wp-plugin ~/.grunt-init/wp-plugin
Then in your WordPress plugin directory, create a new empty directory, switch to it, and run the installer with:
grunt-init wp-plugin
You will be prompted to answer some questions that are used for things like function prefixing and plugin meta. Once this is done, you will need to install the node modules that Grunt relies on, with:
npm install
Installing and using the theme generator is almost exactly the same process. Except to install the template you use:
git clone https://github.com/10up/grunt-wp-theme ~/.grunt-init/wp-theme
And to run it, you use:
grunt-init wp-theme
For both the plugin and theme, you have an assets directory. In there, you will find a directory called JS, and another one called CSS. The JS folder contains a directory called “src.” Any javascript files you create inside of there will be combined and then used to create a second, minified version. One of those files will then be loaded into WordPress. The non-minified version will be used only if the constant SCRIPT_DEBUG is defined as true.
CSS works in a very similar way, except it is created via a precompiler – either SASS or LESS — depending on which one you choose during installation. The SASS or LESS will be compiled to both minified and non-minified versions. Again, SCRIPT_DEBUG determines which one is loaded.
In order to process your JavaScript and SASS (or LESS), you simply switch to the directory for your theme or plugin, and type:
grunt
That’s it. Grunt is truly a magical thing. The plugin template, but not the theme, has an extra task called “build,” which prepares a plugin for release. You can run this task with:
grunt:build
In my next article for Torque, I will be talking more about using Grunt to automate the process of preparing and releasing a plugin.
Both of these templates are very minimal. In fact, the theme is almost a blank slate. You probably will want to fork those repositories and create your own starting points. Also, if you prefer using Tom McFarlin‘s Plugin Boilerplate as your starting point for plugins, be sure to check out grunt-wp-boilerplate by Foo Plugins, which adapts the grunt-wp-plugin for the Plugin Boilerplate.
Site creation
If you’ve been reading my posts in Torque over the last few months, then you know I love using VVV for creating local development environments and using Composer for dependency management. I recently created a starter project for creating a WordPress site in VVV that uses Composer for dependency management.
While that project works, the setup process still requires manually changing a lot of information in the various files. Then, once that’s done, I have to manually run the grunt-wp-theme installer to create the site’s theme. None of that sat well with me, as it violates the proper distribution of labor between humans and computers.
By using 10up’s starter theme and plugins as inspiration, I adapted my VVV plus Composer starter project to use Grunt for automation. I actually incorporated 10up’s grunt-wp-theme. That way, I have a theme ready to go.
I should note, that when compared to 10up’s templates, which are very much a clean-slate, designed for anyone to use, mine are very subjective. For example, I have hardcoded the plugins and themes that I like to work with into the Composer dependencies. Of course, you are welcome to fork it and make it your own.
Using my site generator is very similar to using the other templates I’ve discussed. To install it, simply clone the repository to your .grunt-init directory:
git clone https://github.com/Shelob9/wp-vvv-start-with-grunt ~/.grunt-init
Then, create a new folder in your VVV’s WWW directory, switch into it, and run the installer:
grunt-init wp-vvv-start-with-grunt
You will be asked a series of prompts, the most important being the one for “site_slug.” You must enter the name of the directory you are creating the project in for this value.
Once the installer is done, you can run composer update to bring in your dependencies. You will also notice that you have two theme directories: One is the regular one in the content directory, and the other is a separate one, named for the value of “site_slug.”
Themes in the second directory are not ignored by git, while themes in the standard directory are. The logic behind this is that the theme is specific to the site, and therefore should be included in its version control.
Automate everything
OK, I’ll admit I’m a bit obsessed with automating my development environment these days. Beyond the fact that I find it fun to set these things up, they allow me to reduce repetitive tasks. Reducing repetition leads to less human error and more time spent doing what humans are best at: the creative work.
I think that spending a little bit of time setting up these sorts of automated systems and learning about them is worth it in the long run. Not only do they save time, but they find those savings in the dull parts of our jobs. And that, is one of the many things I find really beautiful about what I am lucky enough to do everyday.
5 Comments