Merge pull request #12 from suitcss/postcss

Switch to PostCSS

Author: simonsmith

.travis.yml

@@ -1,3 +1,4 @@
 language: node_js
+sudo: false
 node_js:
-  - "0.10"
+  - "0.12"

README.md

@@ -5,8 +5,17 @@
 [SUIT CSS](https://github.com/suitcss/suit) preprocessor.
 
 Provides a CLI and Node.js interface for a preprocessor that combines
-[rework-suit](https://github.com/suitcss/rework-suit) with
-[autoprefixer](https://github.com/ai/autoprefixer).
+various [PostCSS](https://github.com/postcss/postcss) plugins.
+
+Compiles CSS packages with:
+
+* [postcss-import](https://github.com/postcss/postcss-import)
+* [postcss-custom-properties](https://github.com/postcss/postcss-custom-media)
+* [postcss-calc](https://github.com/postcss/postcss-calc)
+* [postcss-custom-media](https://github.com/postcss/postcss-custom-media)
+* [autoprefixer](https://github.com/postcss/autoprefixer)
+
+In addition each imported file is linted with [postcss-bem-linter](https://github.com/postcss/postcss-bem-linter).
 
 ## Installation
 
@@ -22,49 +31,114 @@ suitcss input.css output.css
 
 ## API
 
-#### Command Line
+### Command Line
 
 ```
 Usage: suitcss [<input>] [<output>]
 
 Options:
 
-  -c, --compress             compress output
-  -h, --help                 output usage information
-  -i, --import-root [path]   the root directory for imported css files
-  -v, --verbose              log verbose output for debugging
-  -V, --version              output the version number
-  -w, --watch                watch the input file for changes
+  -h, --help                output usage information
+  -V, --version             output the version number
+  -m, --minify              minify output with cssnano
+  -i, --import-root [path]  the root directory for imported css files
+  -c, --config [path]       a custom PostCSS config file
+  -v, --verbose             log verbose output for debugging
+  -w, --watch               watch the input file and any imports for changes
 
 Examples:
 
   # pass an input and output file:
   $ suitcss input.css output.css
 
+  # configure the import root directory:
+  $ suitcss --import-root src/css input.css output.css
+
   # watch the input file for changes:
   $ suitcss --watch input.css output.css
 
+  # configure postcss plugins with a config file:
+  $ suitcss --config config.js input.css output.css
+
   # unix-style piping to stdin and stdout:
   $ cat input.css | suitcss | grep background-color
 ```
 
-#### Node.js
+### Configuration
+
+Creating a configuration file allows options to be passed to the individual PostCSS plugins. It can be passed to the `suitcss` CLI via the `-c` flag and can be either JavaScript or JSON
+
+```js
+module.exports = {
+  root: 'path/to/css',
+  autoprefixer: { browsers: ['> 1%', 'IE 7'], cascade: false },
+  'postcss-calc': { preserve: true }
+}
+```
+
+```js
+{
+  "root": "path/to/css",
+  "autoprefixer": { "browsers": ["> 1%", "IE 7"], "cascade": false },
+  "postcss-calc": { "preserve": true }
+}
+```
+
+Options are merged recursively with the defaults. For example, adding new plugins to the `use` array will result in them being merged alongside the existing ones.
+
+#### Adding additional plugins
+
+By default the preprocessor uses all necessary plugins to build SUIT components. However additional plugins can be installed into a project and then added to the `use` array.
+
+This **will not** work with the preprocessor installed globally. Instead rely on the convenience of `npm run <script>`
+
+```js
+module.exports = {
+  use: [
+    'postcss-property-lookup'
+  ]
+};
+```
+
+```js
+{
+  "name": "my-pkg",
+  "version": "0.1.0",
+  "dependencies": {
+    "postcss-property-lookup": "^1.1.3",
+    "suitcss-preprocessor": "^0.5.0"
+  },
+  "scripts": {
+    "preprocess": "suitcss -c myconfig.js index.css build/built.css"
+  }
+}
+```
+
+```
+npm run preprocess
+```
+
+### Node.js
+
+Returns a [PostCSS promise](https://github.com/postcss/postcss/blob/master/docs/api.md#lazyresult-class)
 
 ```js
 var preprocessor = require('suitcss-preprocessor');
 var fs = require('fs');
 
 var css = fs.readFileSync('src/components/index.css', 'utf8');
 
-var bundle = preprocessor(css, {
-  alias: {
-    'components': 'src/components'
-  },
-  source: 'src/components/index.css',
-  sourcemap: true
+preprocessor(css, {
+  root: 'path/to/css',
+  minify: true,
+  config: {
+    use: ['postcss-property-lookup'],
+    autoprefixer: { browsers: ['> 1%', 'IE 7'], cascade: false },
+    'postcss-calc': { preserve: true }
+  }
+}).then(function(result) {
+  fs.writeFileSync('build/bundle.css', result.css);
 });
-
-fs.writeFileSync('build/bundle.css', bundle);
 ```
 
 ## Acknowledgements

bin/suitcss

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 
-var fs = require('fs');
+var fs = require('fs-extra');
 var exists = fs.existsSync;
 var logger = require('./logger');
 var suitcss = require('..');
 var path = require('path');
 var resolve = path.resolve;
 var program = require('commander');
 var read = require('read-file-stdin');
-var watch = require('node-watch');
-var write = require('write-file-stdout');
+var chokidar = require('chokidar');
+var writeFileSync = fs.outputFileSync;
 
 /**
  * Usage.
@@ -18,10 +18,11 @@ var write = require('write-file-stdout');
 program
   .version(require('../package.json').version)
   .usage('[<input>] [<output>]')
-  .option('-c, --compress', 'compress output')
+  .option('-m, --minify', 'minify output with cssnano')
   .option('-i, --import-root [path]', 'the root directory for imported css files', '')
+  .option('-c, --config [path]', 'a custom PostCSS config file', '')
   .option('-v, --verbose', 'log verbose output for debugging')
-  .option('-w, --watch', 'watch the input file for changes');
+  .option('-w, --watch', 'watch the input file and any imports for changes');
 
 /**
  * Examples.
@@ -39,6 +40,9 @@ program.on('--help', function () {
   console.log('    # watch the input file for changes:');
   console.log('    $ suitcss --watch input.css output.css');
   console.log();
+  console.log('    # configure postcss plugins with a config file:');
+  console.log('    $ suitcss --config config.js input.css output.css');
+  console.log();
   console.log('    # unix-style piping to stdin and stdout:');
   console.log('    $ cat input.css | suitcss | grep background-color');
   console.log();
@@ -56,7 +60,7 @@ program.parse(process.argv);
 
 var input = program.args[0] ? resolve(program.args[0]) : null;
 var output = program.args[1] ? resolve(program.args[1]) : null;
-var importRoot = program.importRoot;
+var config = program.config ? require(resolve(program.config)) : null;
 var verbose = program.verbose;
 var regen = program.watch && input && output;
 
@@ -73,12 +77,25 @@ if (input && !exists(input)) logger.fatal('not found', input);
 run();
 
 /**
- * Watch?
+ * Watch
  */
 
+var currentWatchedFiles;
 if (regen) {
-  watch(input, run);
-  if (verbose) logger.log('watch', input);
+  var watcher = chokidar.watch(input);
+  watcher.on('change', run);
+  watcher.on('change', function(file) {
+    if (verbose) logger.log(path.basename(file) + ' changed');
+  });
+  watcher.on('ready', function() {
+    if (verbose) logger.log('Watching ' + path.basename(input));
+  });
+
+  global.watchCSS = function(imported) {
+    watcher.unwatch(currentWatchedFiles);
+    watcher.add(imported);
+    currentWatchedFiles = imported;
+  };
 }
 
 /**
@@ -90,14 +107,19 @@ function run () {
     if (err) logger.throw(err);
     var css = buffer.toString();
 
-    try {
-      css = suitcss(css, { compress: program.compress, dir: importRoot, source: input });
-    } catch (e) {
-      e.css = css;
-      logger.throw(e);
-    }
-
-    write(output, css + '\n');
+    suitcss(css, {
+      minify: program.minify,
+      root: program.importRoot,
+      config: config
+    }).then(function(result) {
+      if (output) {
+        writeFileSync(output, result.css + '\n');
+      } else {
+        console.log(result.css);
+      }
     if (verbose && output) logger.log('write', output);
+    }).catch(function(e) {
+      logger.throw(e);
+    });
   });
 }

lib/index.js

@@ -1,17 +1,60 @@
 /**
  * Module dependencies
  */
-
+var assign = require('object-assign-deep');
+var without = require('lodash/array/without');
+var last = require('lodash/array/last');
 var autoprefixer = require('autoprefixer');
-var rework = require('rework');
-var suit = require('rework-suit');
+var bemLinter = require('postcss-bem-linter');
+var postcss = require('postcss');
+var cssnano = require('cssnano');
+var reporter = require('postcss-reporter');
 
 /**
  * Module export
  */
 
 module.exports = preprocessor;
 
+var defaults = {
+  minify: undefined,
+  use: [
+    'postcss-import',
+    'postcss-custom-properties',
+    'postcss-calc',
+    'postcss-custom-media',
+    'autoprefixer',
+    'postcss-reporter'
+  ],
+  'postcss-import': {
+    transform: function (css, filename) {
+      return postcss([bemLinter, reporter]).process(css, {from: filename}).css;
+    },
+    root: undefined,
+    onImport: function(imported) {
+      // Update the watch task with the list of imported files
+      if (typeof global.watchCSS === 'function') {
+        global.watchCSS(imported);
+      }
+    }
+  },
+  'postcss-reporter': {
+      clearMessages: true
+  },
+  // http://cssnano.co/optimisations/
+  cssnano: {
+    calc: false,
+    autoprefixer: false,
+    mergeRules: false,
+    // Disable unsafe optimisations
+    zindex: false,
+    discardUnused: false,
+    reduceIdents: false,
+    mergeIdents: false
+  }
+};
+
+
 /**
  * Process CSS
  *
@@ -24,21 +67,46 @@ function preprocessor(css, options) {
     throw new Error('suitcss-preprocessor: did not receive a String');
   }
 
+  options = mergeOptions(options);
+
+  var plugins = options.use.map(function (p) {
+    var plugin = require(p);
+    settings = options[p];
+
+    return settings ? plugin(settings) : plugin;
+  });
+
+  var processor = postcss(plugins);
+
+  if (options.minify) {
+    processor.use(cssnano(options.cssnano));
+  }
+
+  return processor.process(css);
+}
+
+
+/**
+ * Merge options with defaults and set root
+ *
+ * @param {Object} options
+ */
+
+function mergeOptions(options) {
   options = options || {};
+  options.config = options.config || {};
 
-  var browserConfig = options.browsers || [
-    'Explorer >= 9',
-    'last 2 Chrome versions',
-    'last 2 Firefox versions',
-    'last 2 Safari versions',
-    'last 2 iOS versions',
-    'Android 4'
-  ];
+  var merged = assign({}, defaults, options.config);
 
-  css = rework(css, options).use(suit(options)).toString(options);
+  merged.minify = options.minify;
+  merged['postcss-import'].root = options.root;
 
-  // vendor prefixes
-  css = autoprefixer(browserConfig).process(css).css;
+  // Ensure postcss-reporter is always the final plugin
+  if (last(merged.use) !== 'postcss-reporter') {
+    var plugins = without(merged.use, 'postcss-reporter');
+    plugins.push('postcss-reporter');
+    merged.use = plugins;
+  }
 
-  return css;
+  return merged;
 }