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 https://github.com/pattern-lab/patternlab-php.git

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](http://patternlab.io/) - [About Pattern Lab](http://patternlab.io/about.html) - [Documentation](http://patternlab.io/docs/index.html) - [Demo](http://demo.patternlab.io/)",
  "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.
  grunt.initConfig({
    // Task configuration.
    shell: {
      patternlab: {
        command: "php core/builder.php -gp"
      }
    },
    less: {
      build: {
        files: {
          "public/css/style.css": "source/less/style.less"
        }
      }
    },
    watch: {
      html: {
        files: [
          'source/_patterns/**/*.mustache', 
          'source/_patterns/**/*.json', 
          'source/_data/*.json',
        ],
        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.loadNpmTasks('grunt-contrib-watch');
  grunt.loadNpmTasks('grunt-shell');
  grunt.loadNpmTasks('grunt-contrib-less');

  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.

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/

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

If it looks like that, it’s working.

Now go into Chrome and turn on your Live Reload client by clicking the icon:

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

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.

Party

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:

Pattern Lab’s documentation

Thoughts

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.

Tag: live reload

Pattern Lab with Grunt and Live Reload