fetimo / sakugawa

CSS splitter, filter and organiser

Sakugawa (佐久川)

CSS splitter, filter and organiser for IE9 and before

Internet Explorer versions from 6 up to 9 come with a limitation for selectors present in a single CSS file. This limitation of 4095 selectors created the need for CSS splitter, which might be the main use case of this task runner plugin.

Those versions also come with other number related limits, such as the amount of @import rules used in a single file. That limit is 31 for sheets and the imported sheet can have descending imports up to 4 levels total.

Since IE8 and earlier, do not support media queries, but IE9 does, there is an option for handling media queries differently, based on the targeted IE version. By separating media queries in to a different file, it will allow the to include that CSS file conditionally only when IE9 is being used. Ideally this would reduce the amount of bytes downloaded by IE8, which cannot handle the media queries anyhow, and thus prevent downloading something that is not even used.

Background for the name

Mr Sakugawa (佐久川 寛賀, first name Kanga) was a martial artist living in Okinawa, Japan. He was very important figure in the evolution of the Ryukyu martial arts known today as Karate and Ryukyu Kobujutsu. In the latter, there are forms named after him, in which a long six feet wooden staff is used.

The three forms are called Sakugawa no kon sho, Sakugawa no kon chu, and Sakugawa no kon dai. Here is a Youtube video of one of those forms.

Installation

Install globally, in order to use the command line tool. Might need to use sudo, depending of your setup:

npm install --global sakugawa

For local installation, in which you could use --save or --save-dev:

npm install sakugawa

Please note that this tool requires the minimum Node.js version to be 4.2.0, which is the Long Term Support (LTS) version.

Command line usage

Usage: sakugawa [options] huge-stylesheet.css [more CSS files]

Options:

  -h, --help             Show help
  -V, --version          Show version information
  -n, --max-selectors    Maximum number of CSS selectors per output file
  -i, --max-imports      Maximum number of @import rules per output file
  -s, --suffix           Output CSS file suffix
  -M, --minimum-files    Minimum number of output CSS files
  -m, --media-queries    Media query handling, separation to different file (separate) or ignorance (ignore). By default included

Example with Pure CSS:

sakugawa -n 400 -m separate pure-min.css

Would result in creating files pure-min_1.css and pure-min_2.css in which the latter contains all media queries.

Please note that the resulting files are not minified.

The CSS file used in the example can be retrieved with:

wget http://yui.yahooapis.com/pure/0.5.0/pure-min.css

Use as a npm module

First require the sakugawa module, which exports itself as a function.

var sakugawa = require('sakugawa');

Later on in the script use the sakugawa function:

var styles = fs.readFileSync('pure.css', 'utf8');

var options = {
  maxSelectors: 400,
  mediaQueries: 'separate'
};

var separated = sakugawa(styles, options);
// Separated is an array of CSS strings

separated.forEach(function eachPages(css, index) {
  fs.writeFileSync('pure_' + (index + 1) + '.css', css, 'utf8');
});

Available options are shown below and assigned to their default values:

var options = {
  maxSelectors: 4090,
  mediaQueries: 'normal',
  filename: 'input.css', // Not used at the moment for anything
  minSheets: 1
};

The above used options map to the same as used via command line and thus have the same defaults and allowed values. Please note however, that the minSheets is used as --minimum-files via command line, since the command line version is touching files, while the API provided is only touching strings.

Task runners

• gulp-sakugawa
• grunt-sakugawa

Contributing

Please refer to a GitHub blog post on how to create somewhat perfect pull request.

Unit tests are written with tape and can be executed with npm test. Code coverage is inspected with Istanbul and can be executed with npm run coverage. Please make sure it is 100% at all times.

Version history

• v0.5.1 (2015-12-04)
  • Code coverage report at codecov #24
  • ES2015 variable usage. Was going to use destructuring, but it's not released yet in Node.js
• v0.5.0 (2015-11-16)
  • Limit the number of @import rules, #2
  • Version outputs only 0.5.0
  • Require minimum of Node.js LTS version 4.2.0
• v0.4.1 (2015-03-11)
  • One var too many in the previous release
• v0.4.0 (2015-03-11)
  • Preserve @charset rules, #5
• v0.3.2 (2015-02-25)
  • Minimum number of CSS sheets was not followed
  • Code coverage with unit tests at 100%, #1 and #8
• v0.3.1 (2015-02-23)
  • Use latest css version, namely 2.2.0, which was release five days ago
• v0.3.0 (2015-02-23)
  • Possibility to specify minimum amount of generated CSS, #7
• v0.2.1 (2014-12-05)
  • Better documentation and command line bin path configured so now usable via global install
• v0.2.0 (2014-11-19)
  • Speed improvements
• v0.1.0 (2014-11-17)
  • Initial release with splitting against selector count and media query filtering

License

Copyright (c) Juga Paazmaya [e-mail]

Licensed under the MIT license.