Pattern Lab with Grunt and Live Reload

If you haven’t heard of Pattern Lab yet, go check it out. It’s a really cool tool that helps you build atomic design systems. There’s tons of reading over on the official site if you have no clue what any of that means. ๐Ÿ™‚

I can be an efficiency freak, I like everything in my development and build process to be automated. I configured the php version of pattern lab into a node package (which might make some people raise an eyebrow) that allows for some pretty cool features, including:

  • CSS preprocessing (I personally use LESS, but SASS will work too if you make the appropriate adjustments)
  • Live reload

In this tutorial, I’ll walk through basic steps of setting up Pattern Lab with grunt and live reload. No web server needed for this (although you can certainly use one if you want)!

You’ll need:

  • An OS that knows what a proper terminal is ๐Ÿ™‚
  • Git installed on the command line
  • Node.js/npm installed
  • Grunt-CLI installed
  • Slight familiarity with Pattern Lab

I haven’t tested this on a Windows machine, but it should work for Linux/Mac users.

Setting up

If you’ve already set up Pattern Lab, you can probably skip this step.

Open up a terminal window and head to wherever your primary workspace is and clone the patternlab-php repo.

git clone

Now that patternlab-php has a place to live, lets build it for the first time. Your output might look slightly different, but as long as you have no errors, you’re good.

cd patternlab-php
php core/builder.php -g

At this point, you should be able to go to the path you installed patternlab-php in and then navigate to public/index.html and view it. In the case of my example the url would be: file:///Users/jfitzsim/projects/patternlab-php/public/index.html

Now you can edit files in the source/ folder, then rebuild Pattern Lab by running php core/builder.php -g, then refreshing the page to see your changes. If you keep following this article, you’ll eventually be able to edit files in source/ and have your browser automatically refresh with your changes. Before we get there, we’ve got a little work to do.

Nodifying Pattern Lab

Now to keep track of our project dependencies, lets initialize this as a node package. In patternlab-php’s root directory, make a file called package.json and put this in it.

  "name": "patternlab-php",
  "version": "0.0.0",
  "description": "- [Pattern Lab Website]( - [About Pattern Lab]( - [Documentation]( - [Demo](",
  "author": "",
  "license": "MIT",
  "devDependencies": {

What we’re currently most interested with is the devDependencies, which are currently blank. These devDependencies will make it easy for you to share your project with your developer colleagues. Once they pull your project down from git, they only need to type npm install and all the devDependencies will be downloaded.

Now it’s time to beef up our project with some grunt plugins. To do anything useful, you’ll want at least grunt-contrib-less (or sass), grunt-shell, and grunt-contrib-watch (I’ll explain later how to add CSS preprocessing). If you don’t put the --save-dev flag on the commands, your package.json file will not be updated with your devDependencies.

npm install grunt-contrib-less --save-dev
npm install grunt-shell --save-dev
npm install grunt-contrib-watch --save-dev

Quick explanation

grunt-shell will allow us to execute shell commands to automate the building of the patterns that is normally done via command line php.

grunt-contrib-watch will allow us to watch the project for changes then perform whatever task we want (like reload the page, or compile LESS/SASS).

grunt-contrib-less will compile our LESS into CSS. You could use SASS too, grunt is flexible. Do a google search for “grunt sass” and you should be able to find a suitable grunt plugin.

Make your Gruntfile

Now that we’ve installed these grunt plugins, lets put them to work by telling them what to do via our Gruntfile.js. In the patternlab-php root directory, make a new file called Gruntfile.js and put the following in it:

If this is confusing or scary, I highly recommend reading Chris Coyier’s article on grunt which demystifies what is happening here.
module.exports = function(grunt) {

  // Project configuration.
    // Task configuration.
    shell: {
      patternlab: {
        command: "php core/builder.php -gp"
    less: {
      build: {
        files: {
          "public/css/style.css": "source/less/style.less"
    watch: {
      html: {
        files: [
        tasks: [ 'shell:patternlab' ],
        options: {
          spawn: false,
          livereload: true
      styles: {
        files: [ 'source/less/style.less' ],
        tasks: [ 'less' ],
        options: {
          spawn: false,
          livereload: true

  // These plugins provide necessary tasks.

  grunt.registerTask('default', ['build']);
  grunt.registerTask('build', ['shell:patternlab', 'less']);


Now, using grunt-contrib-watch and grunt-shell we can remove one step of having to run that php command. Our watch task will listen for any changes in the directory we specified and when it notices one, it’ll run our build task, which as of right now is equal to running the shell:patternlab task followed by running the LESS task.

Hooking up LESS

The way you structure this is up to you, but here’s the setup I’m working with. This setup is will work with the Gruntfile I provided above.

Screen Shot 2014-04-16 at 2.48.45 PM

Now we’ve got it setup so when you run grunt watch and change your style.less file, it’ll automatically recompile a new CSS file and put it in the appropriate location within public/

Live Reload

Now, lets add in some Live Reload. Download the browser extension of your choice. I’m currently using the Chrome one.

Chrome users: Be sure to enable “Allow access to file URLs” checkbox in Tools > Extensions > LiveReload after installation. Otherwise it won’t work unless you’re running it from a web server.

Run the following command to start up the livereload server: grunt watch

Screen Shot 2014-04-14 at 4.07.16 PM

If it looks like that, it’s working.

Now go into Chrome and turn on your Live Reload client by clicking the icon: Screen Shot 2014-04-14 at 4.09.42 PM

The little circle in the center should fill in it should look like this:

Screen Shot 2014-04-14 at 4.09.02 PM

Now you can open up your style.less file and go to town. Every time you save your .less file, grunt will do the grunt work of building your CSS file.


This allows for super rapid development of styles because you can make the changes and then instantly see how it looks. We’ve completely removed the steps of having to re-build our site, go to the browser, and reload. Also, we’re able to live reload new patterns, which is super convenient.



You now have a bad ass (albeit basic) setup to rock out some design systems. The possibilities are very promising and this tutorial has just scratched the surface. For some additional reading:


I’d recommend using a server of some kind. Otherwise, when your Pattern Lab live reloads, you’ll be brought back to the “View All” page. If you’re running it on an apache server, it should save the page you’re on.

Hope this helps people get up and running with this awesome tool.

11 thoughts on “Pattern Lab with Grunt and Live Reload”

  1. Thanks for this writeup! It came just as I was setting up more or less the same as a way to get better acquainted with both Grunt and Patternlab, so your notes were super helpful.

    One thing I’m running into: Livereload is working but it has to fully reload the page in the browser (i.e. you can see the browser perform an entire new request), it’s not doing the awesome CSS injection when the only thing changing is the compiled CSS file. Not the end of the world, but it’s definitely slower having to wait for the full reload. The only substantive difference in my set up is that I’m using a Compass task to compile the CSS instead of LESS. I spent a lot of time trying to reshuffle the tasks so that the CSS watching + livereload is handled outside of the Pattern Lab build watch task, in hopes that that would help, but then the livereload stopped working entirely. My only thought is that maybe it’s having trouble with livereload because Pattern Lab is rendering into an iframe?

    Anyhow, just curious if your setup is working with the quicker CSS style injection! If so, I’ll go back to tinkering with my configuration…

    1. I’m not sure what you mean by quicker CSS style injection. The animated GIFs I posted are just plain old live reload reloading the whole iframe. If there’s a quicker way to do it, I’d love to know. ๐Ÿ™‚

      1. It’s also entirely possible that I’m confused about whether it’s *supposed* to work properly with CSS injection, but in any case here’s what I was talking about: It might be the case that I need to swap out or combine the Grunt watch task with this newish grunt-style-injector (now renamed grunt-browser-sync?) thing:

        Will have to experiment, and if I figure something amazing out I’ll report back!

        1. I’m still not able to get CSS injection to work with Compass and grunt-contrib-watch’s livereload feature, but I did get it to work using an extra module: grunt-browser-sync! LiveReload still fires for changes to the pattern template files, but now browser-sync watches for changes to the compiled CSS and injects those changes directly to the browser without the full page reload. Changes to the CSS now take only a few ms to show up in the browser instead of the 1 or 2 second lag I was seeing before. You can keep your place on the page as the styles change, too, handy if you’re looking at a lengthy pattern or dealing with modal popups or something like that. As a bonus that I haven’t tested yet, browser-sync also lets you auto-reload on any number of connected devices simultaneously, which would be useful for testing on devices, assuming that it works…

          Here’s my current Pattern Lab + Compass + browser-sync Gruntfile if you want to take a look at how I’ve set it up:

  2. Thank you both, Joseph and Adam, for your contributions to Pattern Lab, it’s pretty cool to have a file open side-by-side with the browser and see the changes right away. I used Joseph’s instructions here combined with Adam’s gruntfile and have things working pretty speedily.

    One thing I was hoping for, however, is a way to get this working to modify and save .scss file from Chrome dev tools (so I can right-click and modify the style directly). Sorry if this is a dumb question (I am not a very strong developer, I am more of a designer who tries to smoosh things together as I go!)– but do you guys think there is a way to get that to work? I tried getting sourcemaps to work, and it generates one for style.css, but it stays in the source folder instead of the public folder (so Chrome doesn’t see it).

    1. I am a little closer to figuring it out– really did not expect to. But again, given your help here, Chris Coyier’s article about Grunt, and the thread below, I added this to my Gruntfile.js:

      compass: {
      scss: {
      options: {
      sourcemap: true

      Only thing is now, I can see the .scss in Chrome Devtools, but as soon as I make a change in the Styles panel, it changes from _text.scss to something like style.css?3509245. And if I edit from the Sources panel and save, I have to manually refresh the page in Chrome. Sigh.

      1. Hi Leanne,

        With the caveat that I haven’t tried this yet with Pattern Lab, I’m able to edit .scss files directly in the Chrome dev tools Sources panel and have the GruntJS watch do its thing with working LiveReload, so this should be doable, unless there’s something about PL that makes it weird.

        You’re right that enabling source maps is the first major step! In order to have the changes you make in the Source panel save back out to your .scss files where Grunt can see them, though, you’ll need to set up the “Workspaces” feature in the dev tools. Here’s a great writeup on that (check out all of the bits about Sass debugging on that page…useful info):

        I also generally don’t know what I’m doing and I’ve never fully jumped into the Workspaces side of the dev tools, so it’s also possible that someone else might have way better suggestions…!

  3. It’s working!! Thanks for that Workspaces article, that did the trick. So awesome.

    The only thing I realized (after being stumped for awhile) is I did need to set livereload to true in Gruntfile.js for sass. The browser sync guy didn’t seem to be working for me otherwise (both from Chrome and when I was trying to edit files from a text editor)

What do you think?