sakugawa

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 the minimum supported version of Node.js is 10.13.0, which is the active 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 (normal)

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

"A Beginner's Guide to Open Source: The Best Advice for Making your First Contribution".

Also there is a blog post about "45 Github Issues Dos and Don’ts".

Linting is done with ESLint and can be executed with npm run lint. There should be no errors appearing after any JavaScript file changes.

Unit tests are written with tape and can be executed with npm test. Code coverage is inspected with nyc and can be executed with npm run coverage after running npm test. Please make sure it is over 90% at all times.

Version history

• v0.7.0 (2021-02-16)
  • Minimum Node.js version lifted from 8.11.1 to 10.13.0
  • Run tests also against Node.js version 14. Now versions 10 (Wercker), 12 (AppVeyor), and 14 (GitHub Actions) of Node.js are covered
  • Suffix option did not accept strings because it was configured as number #40. Fixed by @gluecksmensch #41
• v0.6.0 (2019-01-26)
  • Minimum Node.js version lifted from 4.2.0 to 8.11.1
  • Use npm-shrinkwrap.json for locking the working set of 3rd party dependencies
• v0.5.3 (2016-08-08)
  • Start testing with Windows at AppVeyor
  • Move code coverage from instanbul to nyc
  • Document the default value for --media-queries command line option
• v0.5.2 (2016-07-10)
  • Use Object.assign() for cloning AST object, #26, did not work as assumed
• 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.