grunt-stylus-sprite

Compiles Stylus files and generates sprites using node-sprite.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-stylus-sprite --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-stylus-sprite');

Usage

In your project's Gruntfile, add sections sprite and stylus to the data object passed into grunt.initConfig() as shown in the example below. The sprite task must run at least once before the stylus task because the stylus task uses the output of the sprite task.

grunt.initConfig({
  sprite: {
    options: {
      imagePath: 'app/img',
      imageHttpPath: '/assets',
    },
    build: {}
  },
  stylus: {
    options: {
      banner: '/* This is an example CSS file */',
      includePath: 'app/styles',
    },
    build: {
      files: {
        'build/css/example.css': ['app/styles/example.styl'],
      }
    }
  }
})

The "sprite" task

This task generates sprites using node-sprite. After generating the sprites, a property of the grunt object is set, i.e. grunt.spriteHelper which contains a custom Stylus function that allows defining sprites in Stylus.

Options

Options are passed directly to node-sprite. See its documentation for more options.

options.path

Type: String Default value: null

A path that contains the images to generate sprites. Each sprite should be in its own directory.

options.httpPath

Type: String Default value: null

Base path to use while generating CSS for sprite image URLs.

The "stylus" task

This task compiles Stylus files. Additionally, it uses a property defined in the grunt object, i.e. grunt.spriteHelper which contains a custom Stylus function that allows defining sprites in Stylus.

Options

options.includePath

Type: String Default value: null

Stylus include path.

options.banner

Type: String Default value:

A string that is added to the beginning of the compiled CSS file.

options.compress

Type: boolean Default value: true

Enable or disable CSS compression.

options.customize

Type: function

Hook function for stylus customization.

Example:

function (filename, stylus, s) {
  s.define('url', stylus.url({paths: [__dirname + '/build']}));
  s.use(require('nib')());
}

options.seperate

Type: Boolean

Set true to compile every matched stylus files seperately to same folder instead of concat them.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• 1.1.1 - seperate option added
• 1.1.0 - Pass options of sprite task directly to node-sprite. Add customize option to stylus task.
• 1.0.2 - Add stylus options: firebug and linenos.
• 1.0.1 - Minor fixes.
• 1.0.0 - Initial release.