node-neat

node-sass wrapper for thoughtbot's bourbon neat library

This is a node-sass port of the Neat library. If you are looking for the original Ruby/Rails version, you can find it here.

Contents

Requirements

Installation

To install as a development dependency, run:

npm install --save-dev node-neat

If you need it in production, replace --save-dev with --save.

Usage

To use node-neat with tools like gulp.js, Grunt, or directly with node-sass, provide the path to Neat in your Sass config. There are a couple of convenience methods for this, depending on whether you want Sass to include additional directories or not.

The with() function will include any additional paths you pass as arguments.

Returns an array of paths.

var neat = require('node-neat');
// Any of these will return an array of Neat & Bourbon's paths plus your custom path(s) 
neat.with('path/to/stylesheets')
neat.with('path/to/stylesheets1', 'path/to/stylesheets2')
neat.with(['path/to/stylesheets1', 'path/to/stylesheets2'])

The includePaths property returns an array of Neat & Bourbon's paths to use in your config.

var neat = require('node-neat');
neat.includePaths // Array of Neat paths 

Use either method above with the Sass config for your chosen tool (gulp.js, Grunt, etc.), then it's business as usual for Neat & Bourbon in your stylesheet:

@import "bourbon";
@import "neat";

Using the gulp-sass plugin.

var gulp = require('gulp');
var sass = require('gulp-sass');
 
gulp.task('sass', function () {
  gulp.src('path/to/input.scss')
    .pipe(sass({
      // includePaths: require('node-neat').with('other/path', 'another/path') 
      // - or - 
      includePaths: require('node-neat').includePaths
    }))
    .pipe(gulp.dest('path/to/output.css'));
});

The grunt-sass task uses node-sass (LibSass) underneath, and is the recommended way to use Grunt with node-neat.

Example config:

grunt.initConfig({
  sass: {
    dist: {
      options: {
        // includePaths: require('node-neat').with('other/path', 'another/path') 
        // - or - 
        includePaths: require('node-neat').includePaths
      },
      files: {
        'path/to/output.css': 'path/to/input.scss'
      }
    }
  }
});

If you are using the Ruby version of Sass with node-neat, then you will need to use the grunt-contrib-sass task instead.

Note that node-neat is NOT tested against the Ruby version – only against LibSass.

Example config:

grunt.initConfig({
  sass: {
    dist: {
      options: {
        // loadPath: require('node-neat').with('other/path', 'another/path') 
        // - or - 
        loadPath: require('node-neat').includePaths
      },
      files: {
        'path/to/output.css': 'path/to/input.scss'
      }
    }
  }
});

Using it directly with node-sass.

var sass    = require('node-sass')
var neat = require('node-neat');
 
sass.render({
  file: './application.scss',
  successfunction(css){
    console.log(css);
  },
  errorfunction(error) {
    console.log(error);
  },
  // includePaths: neat.with('other/path', 'another/path'), 
  // - or - 
  includePaths: neat.includePaths,
  outputStyle: 'compressed'
});

Getting Help

Feel free to tweet me with questions @iamlacroix, or open a ticket on GitHub.

Testing

node-neat is tested against the examples provided in the Neat documentation. The tests check for compile errors, so if a feature compiles but the expected output is incorrect, be sure to open a ticket.

Run the tests with:

make test

Credits

This node-sass port is maintained by Michael LaCroix, however all credits for the Bourbon Neat library go to thoughtbot, inc:

Neat is maintained and funded by thoughtbot, inc. Tweet your questions or suggestions at @kaishin and @kylefiedler.

License

node-neat is Copyright © 2013-2014 Michael LaCroix. It is free software, and may be redistributed under the terms specified in the LICENSE file.