In this tutorial, we are going to take a look at how to use Grunt, specifically to aid and speed up your WordPress development workflow.
Grunt is a JavaScript task runner installed via NPM that runs on your server. To use the information in this tutorial, you will need command-line access to a server. For the sake of brevity, I refer you to this tutorial for getting Grunt up and running and ready for use.
Grunt is a proven task runner, used in many different ways, across many different platforms. Here, we're going to look at defining a solid foundation on which to base your WordPress development.
Common Tasks
Grunt's community is incredibly strong, which has lead to the development of an immense catalog of plugins. It's easy to get lost and spend a lot of time searching for, and vetting, which ones to use.
So what are some common tasks any WordPress theme or plugin need to accomplish or provide?
- Localizing language strings using the WordPress translation functions
- Management of asset files. That is, working with development and minified versions of both JavaScript and CSS files.
Localization
Grunt has a very successful WordPress-specific localization package called grunt-wp-i18n. This Grunt package is invaluable as it will scan your theme / plugin folder, find all translation strings, and compile a .pot file in the specified location. This .pot file can then be used to convert .po and .mo files for other users to translate your theme / plugin.
To configure the package, add the following to your Gruntfile.js initConfig options:
makepot: {
target: {
options: {
include: [
'path/to/some/file.php'
],
type: 'wp-plugin' // or `wp-theme`
}
}
}
Then call the Grunt task like so (while in the Gruntfile.js folder):
grunt makepot
Your entire folder being scanned and all strings complied to a pot file.
Asset Files
All themes and plugins regularly use JavaScript and CSS files. Unfortunately, a lot of the time the need for development and production versions of the files is overlooked.
Taking cues from WordPress itself, I aim to make sure i have fully commented and minified files:
filename.jsfilename.min.jsfilename.cssfilename.min.css
Why? I like to know what's going on in those files, but I also like to know my visitors are being served optimized versions of the files.
To do so without some form of task runner would mean switching the asset URLs registered in WordPress during development to view the changed, un-minified version, using some form of JavaScript and CSS compressor before releasing an update, and then switching the registered URLs back. And that's no fun.
With Grunt, you can use the Uglify package to minify and optimize JavaScript files on the fly, and to take CSS further we can use the Sass task to compile Sass files into CSS on the fly, as well. For what it's worth, I use Sass because that is what WordPress uses under the hood, but there a LESS compiler for Grunt, as well.
uglify: {
dist: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.min.js <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
report: 'gzip'
},
files: {
'assets/js/filename.min.js' : [
'assets/path/to/file.js',
'assets/path/to/another/file.js',
'assets/dynamic/paths/**/*.js'
]
}
},
dev: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.js <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
beautify: true,
compress: false,
mangle: false
},
files: {
'assets/js/filename.js' : [
'assets/path/to/file.js',
'assets/path/to/another/file.js',
'assets/dynamic/paths/**/*.js'
]
}
}
}
sass: {
dist: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.min.css <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
style: 'compressed'
},
files: [{
expand: true,
cwd: 'assets/scss',
src: [
'*.scss'
],
dest: 'assets/css',
ext: '.min.css'
}]
},
dev: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.css <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
style: 'expanded'
},
files: [{
expand: true,
cwd: 'assets/scss',
src: [
'*.scss'
],
dest: 'assets/css',
ext: '.css'
}]
}
}
Tip: If using the sass task add .sass-cache to your .gitignore to prevent the compiler cache being added to your repository.
Advanced Tasks
We have covered two key areas Grunt can aid in WordPress development, but let's take it a step further and find the additional power in using a task runner.
Watching Files
We are already providing tasks to work on files so why not optimize it? With the task above, we would need to run grunt *** every time we made a change, why not install the grunt-contrib-watch package? Once configured, this will instruct Grunt to run those tasks every time a file change is detected.
grunt watch
Presto! No more running Grunt on every file change, just start the watcher and edit your files.
JavaScript Quality
Wouldn’t it be nice to run JSHint on our JavaScript files to track down those bugs or missing semicolons? Just install the grunt-contrib-jshint task and it to the watcher task before files are compiled. Now Grunt will warn you of any errors and stop running further tasks.
jshint: {
files: [
'assets/js/filename.js',
'assets/dynamic/paths/**/*.js'
],
options: {
expr: true,
globals: {
jQuery: true,
console: true,
module: true,
document: true
}
}
}
Combining Assets
This has been especially useful for me when developing the Fluent Framework. The Fluent Framework is a set of classes that, among other things, create options pages and meta boxes.
To make developing single fields easier, I have a file structure like this:
assets/
├── js/
| ├── filename.js
├── fields/
├── text/
| ├── js/
| ├── text.js
├── select/
├── js/
├── select.js
This makes it really easy to find the field I’m working on and alter only the JavaScript needed for that field.
From a user point of view, I just want to serve a single JavaScript file with all of the common and field based JavaScript combined. Let's use the grunt-contrib-uglify task to accomplish this.
uglify: {
dist: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.min.js <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
report: 'gzip'
},
files: {
'assets/js/filename.min.js' : [
'assets/path/to/file.js',
'assets/path/to/another/file.js',
'assets/dynamic/paths/**/*.js'
]
}
},
dev: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.js <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
beautify: true,
compress: false,
mangle: false
},
files: {
'assets/js/filename.js' : [
'assets/path/to/file.js',
'assets/path/to/another/file.js',
'assets/dynamic/paths/**/*.js'
]
}
}
}
With this configuration, after it passes JSHint, it will combine all the JavaScript files into a development file and production file.
Copy Files
WordPress.org requires a Readme.txt file detailing the theme / plugin information, but version control systems like GitHub and BitBucket prefer Readme.md files. We don’t need manually duplicate or keep these files in sync. Let's just let Grunt do that for us!
Install the grunt-contrib-copy task and configure it like so:
copy: {
dist: {
src: 'readme.txt',
dest: 'README.md'
}
}
Download Data
Another helpful Grunt task is Grunt cURL package. One of the Fluent Framework Fields needed access to the Google Fonts API data. Loading this as Google reccomends would be an HTTP request every time the page is loaded. Alternatively, if you manually copy the contents of the file down, you run the risk of getting out of date. The best of both worlds is to use Grunt Curl to save us a request and get updates.
To keep up-to-date, we simply loaded the cURL task, gave it the URL to fetch font data from, and where to save the response.
curl: {
'google-fonts-source': {
src: 'https://www.googleapis.com/webfonts/v1/webfonts?key=*******',
dest: 'assets/vendor/google-fonts-source.json'
}
}
Now, every time we run the task, the latest font list is downloaded, and saved to the framework file.
Documentation
This task is best used on themes, plugins, and frameworks where a lot of developery eyes will be prying. And context is never a bad thing for those poking around the codebase.
PHP Documentor is a great tool for auto-generating that data. It also helps you focus on providing meaningful DocBlocks in your code.
phpdocumentor: {
dist: {
options: {
ignore: 'node_modules'
}
}
}
Tip: Add docs to your .gitignore if you don’t want to commit the documentation and all of its cache files.
Putting It All Together
Here is the package.json and the Gruntfile.js for the tasks detailed above.
package.json
{
"name": "package-name",
"version": "1.0.0",
"description": "...",
"main": "filename.php",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"type": "git",
"url": "http://repo-url.com"
},
"keywords": [
"wordpress"
],
"author": "Your Name",
"license": "GPL",
"devDependencies": {
"grunt": "~0.4.2",
"grunt-contrib-copy": "~0.5.0",
"grunt-contrib-jshint": "~0.8.0",
"grunt-contrib-sass": "^0.7.3",
"grunt-contrib-uglify": "~0.3.3",
"grunt-curl": "*",
"grunt-phpdocumentor": "~0.4.1",
"grunt-wp-i18n": "~0.4.0"
}
}
Gruntfile.js
module.exports = function(grunt) {
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
copy: {
dist: {
src: 'readme.txt',
dest: 'README.md'
}
},
curl: {
'google-fonts-source': {
src: 'https://www.googleapis.com/webfonts/v1/webfonts?key=*******',
dest: 'assets/vendor/google-fonts-source.json'
}
},
makepot: {
target: {
options: {
include: [
'path/to/some/file.php'
],
type: 'wp-plugin' // or `wp-theme`
}
}
},
jshint: {
files: [
'assets/js/filename.js',
'assets/dynamic/paths/**/*.js'
],
options: {
expr: true,
globals: {
jQuery: true,
console: true,
module: true,
document: true
}
}
},
phpdocumentor: {
dist: {
options: {
ignore: 'node_modules'
}
}
},
sass: {
dist: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.min.css <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
style: 'compressed'
},
files: [{
expand: true,
cwd: 'assets/scss',
src: [
'*.scss'
],
dest: 'assets/css',
ext: '.min.css'
}]
},
dev: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.css <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
style: 'expanded'
},
files: [{
expand: true,
cwd: 'assets/scss',
src: [
'*.scss'
],
dest: 'assets/css',
ext: '.css'
}]
}
},
uglify: {
dist: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.min.js <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
report: 'gzip'
},
files: {
'assets/js/filename.min.js' : [
'assets/path/to/file.js',
'assets/path/to/another/file.js',
'assets/dynamic/paths/**/*.js'
]
}
},
dev: {
options: {
banner: '/*! <%= pkg.name %> <%= pkg.version %> filename.js <%= grunt.template.today("yyyy-mm-dd h:MM:ss TT") %> */\n',
beautify: true,
compress: false,
mangle: false
},
files: {
'assets/js/filename.js' : [
'assets/path/to/file.js',
'assets/path/to/another/file.js',
'assets/dynamic/paths/**/*.js'
]
}
}
}
});
grunt.loadNpmTasks('grunt-contrib-copy');
grunt.loadNpmTasks('grunt-contrib-jshint');
grunt.loadNpmTasks('grunt-contrib-sass');
grunt.loadNpmTasks('grunt-contrib-uglify');
grunt.loadNpmTasks('grunt-curl');
grunt.loadNpmTasks('grunt-phpdocumentor');
grunt.loadNpmTasks('grunt-wp-i18n');
grunt.registerTask('default', [
'jshint',
'uglify:dev',
'uglify:dist',
'sass:dev',
'sass:dist',
'makepot',
'copy'
]);
grunt.registerTask('docs', [
'phpdocumentor:dist'
]);
grunt.registerTask('googlefonts', [
'curl:google-fonts-source'
]);
};
Tip: Add node_modules and npm-debug.log to your .gitignore to prevent the tasks as associated files being added to your repository.
Conclusion
As you can see from the tasks above, Grunt can be used to help automate WordPress development and give you more time to focus on writing code, not managing it.
We have detailed just a few tasks for WordPress, but there are many other packages out there for project specific needs, like image optimization tasks and much, much more, so go exploring!
Grunt is now a well established task runner, and the documentation is on par with WordPress itself, why not consider making a task not already thought of and sharing it with the community?
Comments