supple-preprocessor

supple-preprocessor - 0.0.3

Provides a Command Line Interface(CLI) and a Node.js interface to work with Supple. It compiles CSS packages with:

• postcss-easy-import
• postcss-color-function
• postcss-apply
• postcss-custom-media
• postcss-autoprefixer

Each file is linted by stylelint with the stylelint-config-supple preset. Optional minification is handled by cssnano.

Additional plugins can be added via the configuration options.

Installation

npm:

npm install supple-preprocessor --save-dev

yarn:

yarn add supple-preprocessor --dev

Usage

supplecss input.css output.css

API

Command Line

Options are documented below

Usage: supplecss [<input>] [<output>]

Options:

  -h, --help                output usage information
  -c, --config [path]       a custom PostCSS config file
  -i, --import-root [path]  the root directory for imported css files
  -s, --encapsulate         encapsulate component styles
  -w, --watch               watch the input file and any imports for changes
  -m, --minify              minify output with cssnano
  -e, --throw-error         throw an error when any warnings are found
  -L, --no-lint             disable stylelint and postcss-bem-linter
  -v, --verbose             log verbose output for debugging
  -V, --version             output the version number

Examples:

  # pass an input and output file:
  $ supplecss input.css output.css

  # configure the import root directory:
  $ supplecss --import-root src/css input.css output.css

  # watch the input file and imports for changes:
  $ supplecss --watch input.css output.css

  # configure postcss plugins with a config file:
  $ supplecss --config config.js input.css output.css

Node.js

Returns a PostCSS promise

preprocessor(css: String [, options: Object] [, filename: String]);

• css: CSS input (required)
• options: Options to the preprocessor (see below) (optional)
• filename: Filename of the input CSS file (optional)

Example

var preprocessor = require('supple-preprocessor');
var fs = require('fs');

var filename = 'src/index.css';
var css = fs.readFileSync(filename, 'utf8');

preprocessor(css, {
  root: 'path/to/css',
  minify: true,
}, filename).then(function(result) {
  fs.writeFileSync('dist/bundle.css', result.css);
});

Options

root

• Type: String
• Default: process.cwd()

The path where to resolve imports from. It is then passed to postcss-import.

lint

• Type: Boolean
• Default: true

Ensure code conforms to the Supple code style by using the stylelint-config-supple package.

Stylelint configuration options can also be overridden but this requires the stylelint-config-supple to be installed locally in your package.

{
  stylelint: {
    extends: 'stylelint-config-supple',
    rules: {
      indentation: [4, 'tab'],
    }
  }
}

minify

• Type: Boolean
• Default: false

If minify is set to true then the output will be minified by cssnano.

postcss

• Type: Object
• Default: undefined

Options that are passed directly to postcss, as per the documentation.

{
  postcss: {from: 'filename.css'}
}

use

• Type: Array
• Default: undefined

A list of plugins that are passed to PostCSS. This can be used to add new plugins and/or reorder the defaults

{
  use: ['postcss-at2x', 'postcss-property-lookup']
}

<plugin-name>

• Type: Object
• Default: undefined

Property matching the name of a PostCSS plugin that has options for that plugin

{
  'postcss-calc': { preserve: true }
}

Plugin configuration

Creating a configuration file allows options to be passed to the individual PostCSS plugins. It can be passed to the supplecss CLI via the -c flag and can be either JavaScript or JSON

module.exports = {
  root: 'path/to/css',
  'postcss-calc': { preserve: true }
}

{
  "root": "path/to/css",
  "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 Supple components. However additional plugins can be installed into a project and then added to the use array. They will be appended to the existing list of plugins.

Note: This will not work with the preprocessor installed globally. Instead rely on the convenience of npm run script

module.exports = {
  use: [
    'postcss-property-lookup'
  ]
};

{
  "name": "my-pkg",
  "version": "0.1.0",
  "dependencies": {
    "postcss-property-lookup": "^1.1.3",
    "supple-preprocessor": "^0.0.1"
  },
  "scripts": {
    "preprocess": "supplecss -c myconfig.js index.css build/built.css"
  }
}

npm run preprocess

Changing plugin order

If duplicate plugins are used they will be removed, but the new order will be respected. This is useful if you need to change the default order:

// Default order
var defaults = [
  'postcss-custom-properties',
  'postcss-calc',
  'postcss-color-function',
  'postcss-custom-media',
  'postcss-apply',
];

// config
module.exports = {
  use: [
    'postcss-at2x',
    'postcss-calc',
  ]
};

var result = [
  'postcss-custom-properties',
  'postcss-color-function',
  'postcss-custom-media',
  'postcss-apply',
  'postcss-at2x',
  'postcss-calc',
];

Note Some core plugins such as postcss-easy-import and autoprefixer cannot be re-ordered. This is to ensure components are preprocessed correctly.

Autoprefixer: vendor prefixes

The preprocessor tries to find any browserslist config files. If it cannot find any it will fallback to the autoprefixer default.

Acknowledgements & Credits

Based on Myth by Segment.io.