RECESS

Overview

Developed at Twitter to support our internal styleguide, RECESS is a simple, attractive code quality tool for CSS built on top of LESS.

Incorporate it into your development process as a linter, or integrate it directly into your build system as a compiler, RECESS will keep your source looking clean and super managable.

Installation

Run the following line in your terminal:

$ npm install recess -g

Note: You'll need to have Node.js and NPM installed.

What It Does

Use RECESS as a linter to keep your styles tidy and consistent.

The rules are as follows (you can disable individual rules if you don’t want to abide by them):

» noIDs - Don’t style IDs like #foo
» noJSPrefix - Don’t style .js- prefixed classnames
» noOverqualifying - Don’t overqualify your selectors, like div#foo.bar
» noUnderscores - Don’t use underscores when naming classes, like .my_class
» noUniversalSelectors - Don’t use the universal selector, *
» zeroUnits - Don’t add the unit to a value of 0, like 0px
» strictPropertyOrder - Enforce a strict property order (order defined here)

RECESS can also compile your styles! Powered by the LESS tokenizer, this means you can compile both CSS and LESS source files directly. The compiler will normalize whitespace, strip units from 0 values, and reorder your properties for you.

CSS Input

.avatar img{
  -ms-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
  -webkit-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
  -moz-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
  box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
  -o-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
}

RECESS Output

.avatar img {
  -webkit-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
     -moz-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
      -ms-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
       -o-box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
          box-shadow: inset 0 1px 5px rgba(0, 0, 0, 0.2);
}

Command Line Interface

RECESS is first and foremost a command line tool. It takes a path and optional arguments.

$ RECESS ./CSS/application.css [--options]

In addition to the rules above you can specify the following options:

» help - provides a quick cli cheatsheet
» compile - outputs your compiled source
» includePath - additional directory to look in for relative LESS imports (repeat for each additional directory)
» compress - outputs your compiled source, but minified
» watch - watch a directory and automatically compile a file when changes occur

An example of linting all CSS files in a project but ignoring ID and underscore validation might look something like this:

$ RECESS ./CSS/* --noIDs false --noUnderscores false

You will probably find it desirable to keep your configuration options in a .recessrc file. An example config file might look like this:

{
  "includePath": ["imports"]
, "noIDs": false
, "noJSPrefix": false
, "noUniversalSelectors": false
}

By default, if no --config path is provided, RECESS will check for a local .recessrc file.

Programmatic API

RECESS also provides a programmatic API for linting and compiling. This might be useful when integrating RECESS directly into your build process. The API accepts a path (or array of paths), an optional options object, and an optional callback (fired when RECESS finishes processing your files).

require('recess')(path, options, callback)

Available options and their defaults:

» compile - false
» compress - false
» includePath - []
» noIDs - true
» noJSPrefix - true
» noOverqualifying - true
» noUnderscores - true
» noUniversalSelectors - true
» strictPropertyOrder - true
» zeroUnits - true

Compiling the file fat.less might look like this:

var recess = require('recess')

recess('./js/fat.less', { compile: true }, function (err, obj) {
  if (err) throw err
  console.log(
    obj        // recess instance for fat.less
  , obj.output // array of loggable content
  , obj.errors // array of failed lint rules
  )
})

Note: If you pass multiple files into RECESS, obj will contain an array of RECESS instances.

Issues or Feedback

If you have any problems, concerns, or just want to say hi please let me know by filing a github issue here or messaging me on twitter at @fat. Thanks!

Code licensed under the Apache License v2.0. Documentation licensed under CC BY 3.0.