Converting Gulp into Coffee

I originally wrote all of my Gulp stuff using vanilla Javascript for one reason, and that was because from what I had seen, it was somewhat annoying to use Gulp with CoffeeScript, at least out of box.

I had a friend show me a way to easily integrate CoffeeScript into Gulp, and I’m not looking back.

If you didn’t notice before, I use a modular approach to organizing my Gulp, so I have quite a few JS files to convert. Needless to say, I didn’t want to have to do it manually, so I found some tools to help automate.

Here’s how quickly you can do it:

1) Install JS2Coffee.

shell
1
npm install -g js2coffee

2) Install this awesome script to convert all of your Javascript into Coffee recursively within a directory.

shell
1
2
3
$ touch /usr/local/bin/all2coffee
$ vim /usr/local/bin/all2coffee
# (...insert code and save file, and set permissions)

3) Convert all of your Javascript files and Gulpfile into CoffeeScript, then remove all the JS.

shell
1
2
3
$ cd gulp/
$ all2coffee
$ rm -rf **/*.js

4) Add a simple Gulpfile.js with this in it:

gulpfile.js
1
2
require('coffee-script/register');
require('./gulpfile.coffee');

You should be good to go!

Generating Style Guides with KSS

Documenting style will always be a challenge. I think it’s up to you to decide the project’s balance between:

  • The need for providing clear documentation.
  • The practical use a styleguide would actually serve to the project’s stakeholders

And here’s the key one I’ve usually found a challenge on most projects:

For a style guide to be effective and worth your time,

It takes the concern and vested interest of the other developers on the team to carefully contribute to the documentation, while sticking to a set of style structure and organization.

This last one is always a problem. I’ve found that on the many projects I’ve been involved with, more often than not, the prjoect turns into a mess of tangled CSS code and rules. It doesn’t matter how well we structure the files and folders from the beginning; when push comes to shove, deadlines and pressure cause us to be messy developers. I’m guilty of it as well.

On this particular project, the team already had a style guide set up using static HTML. I knew there had to be a better way, and I found a perfect way to do it.

That’s where Knyle Style Sheets come in. The developer, Kyle Neath seems to enjoy the way Github does it and has created a nice solution to do it. It automatically parses your .scss, .less, or .css files when you write in the approrpiate syntax and generates some static HTML for you.

Unfortunately, when it comes to the grunt and node stack, it was really tricky for me to get it spinning up.

I ended up finding a winning combination: I used grunt-styleguide and this awesome template, plus a couple hacks to get it working.

I’ll leave out the entire Gruntfile. Our project compiles styles from assets/styles into the public/css/ directory.

styleguide task:
Gruntfile.coffee
1
2
3
4
5
6
7
8
9
10
11
styleguide:
  options:
    template:
      src: 'assets/vendor/styleguide-template'
    framework:
      name: 'kss'
      options:
        includeType: 'sass'
        includePath: 'public/css/application.css'
  all:
    files: ['_styleguide': 'assets/styles/**/*.scss']

assets/vendor/styleguide-template is a clone of the template repo mentioned earlier, with some minor customizations to the template.

This task generates static HTML/CSS for a styleguide into the _styleguide directory.

The tricky part was getting my styles to show up in the outputted code. Unfortuantely, though the grunt-styleguide docs say you can run precompiled code through and it will take care of the rest, no matter how hard I tried, that didn’t work.

In the end, it was just a simple matter of adding to my copy and watch tasks to copy the compiled CSS over.

watch task:
Gruntfile.coffee
1
2
3
4
5
6
7
8
9
10
11
12
watch:
  options:
    livereload: false
    spawn: false

  'sass-application':
    livereload: false
    files: [
      'assets/styles/application.scss',
      'assets/styles/**/*.scss'
    ]
    tasks: ['sass:application', 'copy:styles', 'styleguide']
copy:styles task:
Gruntfile.coffee
1
2
3
4
5
6
7
8
copy:
  styles:
    files: [
      expand: true
      cwd: 'public/css'
      src: '**/*'
      dest: '_styleguide/css'
    ]

As a bonus, add grunt-contrib-connect and have it boot up a little preview server. This was helpful on a project I was running because index.html wasn’t accessible.

Gruntfile.coffee
1
2
3
4
5
6
7
8
9
connect:
  styleguide:
    options:
      port: 9001
      base: '_styleguide'
      keepalive: true
      open:
        target: 'http://localhost:9001'
        appName: 'Google Chrome'

Pretty cool, huh? Now, in my _modules.scss file, I can add this before the code block I want to add:

_modules.scss
1
2
3
4
5
6
7
// Spacer
//
// A basic separator element to break up sections.
//
// Markup: <div class="spacer"></div>
//
// Styleguide 2.1

The kss-node project is pretty finicky, but when it works, it’s awesome. You can add modifier classes, and it will generate nice code samples and output for each of those modifier classes. You can even add markdown within your descriptions.

_modules.sass
1
2
3
4
5
6
7
8
9
10
// Alerts
//
// Indicate failure or success. <em>Required: `alert-success` or `alert-error`</em>
//
// Markup: <div class="alert {$modifiers}">You mistyped your password.</div>
//
// .alert-error - Indicate an error
// .alert-success - Indicate success
//
// Styleguide 2.2
Screenshot:

If you find things aren’t working, check to make sure you’re numbering things in the right order, that you haven’t already documented a section. I had to move a few of my sections around to match the order of the @import statements in my main .scss file.

You can pretty quickly and easily customize that template as well, if needed.

Here’s to hoping this helps our team stay on a solid set of rules and continued documentation!