An Intro Into Using Grunt For WordPress Project Scaffolding
In my last post I shared how I lost my Grunt virginity and how I used 10up’s repository to dive into Grunt to learn about how Grunt functions. The 10up repo that Eric contributed to got me up to speed very quickly. I also lent a hand to convince Paul Gibb’s to add some Grunt “magic” to look after some mundane tasks in his incredible Achievements WordPress plugin. (P.S. I know I owe you a feature for Achievements Paul! #toomanythingstodo)
How could I start to automate our internal themes?
After using Grunt in my workflow every day for a month and a half, I had the opportunity to automate the setup process of our bespoke WordPress themes that we build for our clients. We normally start our work based on Underscores, Twenty Twelve or Twenty Eleven. If we are using Twenty Twelve or Twenty Eleven then we’ll gut it completely in terms of CSS and keep the underlying templates. I realised we needed to automate the setup of Underscores with a more fine grained control. I wanted to make sure we had Grunt in our custom theme out of the box, I wanted to delete template files we might not use on setup and add in Sass & Compass.
N.B. Using automation in our workflow is something that I’m going to blog about further on our company blog in the next fortnight as we’ve been working on full automation and I want to do a ‘client friendly’ (read: non geeky) way!
Introducing Underscores WP Theme v0.1.0
After 3 – 4 hours work I’ve released an Initial Release of our Underscores WP Theme. I’ve added an animated gif in the Demo section so you can visually see what happens when you use `grunt-init` and `grunt` to look after your project scaffolding. For this repo/demo I’ve used Grunt with Underscores to look after some mundane tasks such as:
- Creating headers comments for style.scss which Grunt uses to generate style.css when you run `grunt`.
- Adding prompts to ask which template files you’d like and deleting any templates you don’t want in your custom Underscores theme!
- Prefixing your functions throughout the theme.
- Adding info throughout your theme. i.e. comments, text domains and package names.
- Copying across the files you’d into your originally empty theme folder.
- Renaming the _s.pot file.
- Generating your style.css based on all the Sass partials contained in the `sass` folder
N.B. I’m still using loads of magic that Eric Mann covers in his talk on Automated WordPress Development…and I just literally just found out that his had this repository so I could’ve forked this repo before I even started this yesterday arvo and added my extra prompts and Sass stuff in less time #fail. I’ll still plough on with my post because after a quick look over the repo there are still a few things that differ and the purpose of this post is to introduce the basics of Grunt. I wish I was following Eric on Github when he created that repo!
The basics of Grunt for project scaffolding
I’m sure you’re wondering what’s going on when you run `grunt-init underscores-wp-theme` right? Here’s what `grunt-init` does when it runs:
- It’ll look for a template.js which contains a bunch of info about command line output, prompts and dependencies.
- It’ll then look for any rename rules you have for your repo.
- After that it will copy all of the files in the root folder and put them into our empty directory (In our case it won’t copy all of them because of our prompts).
- Grunt will then process all the files and replace any templating tags we’ve used with anything we’ve entered into the command line prompts. (Once again in our case it won’t process all of the files because I noticed that Grunt would process our screenshot.png too which would corrupt it, so I worked around that here.)
- Last but not least it’ll generate a package.json for you.
Template tags
There are loads of template tags that `grunt-init` will lovingly process for you when it runs. Grunt will do a find and replace across all the files that you have in your `root` folder and replace them with the data you’ve answered in the command line prompts.
You’ll see template tags across the entire repo but the best files to look at for a condensed example of said tags are:
- https://github.com/sennza/underscores-wp-theme/blob/master/template.js#L30
- https://github.com/sennza/underscores-wp-theme/blob/master/root/sass/style.scss
- https://github.com/sennza/underscores-wp-theme/blob/master/root/functions.php
See how awesome this is? Grunt’s using the data you entered into the command line prompt and replace all references throughout your theme!
I kinda get it but what now?
This is definitely only an intro tutorial into using Grunt for project scaffolding and I definitely haven’t covered the next most important file in the repo yet. That’s both because in it’s current state it still has traces of Erics’ commits in from the 10up repo which I need to clean out and because most people need to learn new things in digestible pieces.
Any questions?
I’m not sure if I covered too much or too little in this post but that’s what the comments are for! I’m not one of those peeps who forces you to comment about a post via Twitter, so please revel in that and make use of the comments if you have anything to say! I’m pretty sure there will be typo’s and terrible grammar so at least comment on that!
