Configuration file

When using CLI, Pleeease's options have to be set in a file called .pleeeaserc (JSON-like). For example:

{
  "in": ["foo.css", "bar.css"],
  "out": "baz.css",
  "browsers": ["last 3 versions", "Android 2.3"]
}

in

Defines input file(s).

out

Defines output file.

browsers

Allows you to override many options in one go. Accept same value as autoprefixer.browsers and override it, based on CanIUse database (exactly as Autoprefixer)

For example, if you set:

{
  "browsers": ["ie 9"]
}

You will automatically have:

{
  "autoprefixer": { "browsers": ["ie 9"] },
  "rem": false,
  "opacity": false,
  "pseudoElements": false
}

Then, you can override all postprocess options the same way.

Preprocessors

This in an experimental feature. Pleeease includes most famous CSS preprocessors.

• sass
• less
• stylus

sass

Preprocesses your CSS using Sass. It uses libsass.

{
  "sass": true
}

less

Preprocesses your CSS using LESS.

{
  "less": true
}

stylus

Preprocesses your CSS using Stylus.

{
  "stylus": true
}

Postprocessors

Features can be disabled with the false keyword or modified using each postprocessor options. See each features:

• autoprefixer, filters, rem, pseudoElements, opacity
• import, rebaseUrls, minifier, mqpacker
• sourcemaps

The default options are:

{
  "autoprefixer": true,
  "filters": true,
  "rem": true,
  "pseudoElements": true,
  "opacity": true,

  "import": true,
  "minifier": true,
  "mqpacker": false,

  "sourcemaps": false
}

autoprefixer

Adds vendor prefixes to CSS, using Autoprefixer. From Autoprefixer options, you can specify the browsers you want to target in your project:

• last 2 versions is last versions for each browser
• last 2 Chrome versions is last versions of the specified browser.
• > 5% is browser versions, selected by global usage statistics.
• Firefox > 20 is Firefox versions newer than 20.
• Firefox >= 20 is Firefox version 20 or newer.
• ios 7 to set browser version directly.
• none clean CSS from any vendor prefixes.

For example:

{
  "autoprefixer": {"browsers": ["last 4 versions", "ios 6"]}
}

Autoprefixer converts this file:

.element {
  display: flex;
  flex-direction: column;
  background: linear-gradient(red, blue);
}

To this one:

.element {
  display: -webkit-box;
  display: -webkit-flex;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: vertical;
  -webkit-box-direction: normal;
  -webkit-flex-direction: column;
      -ms-flex-direction: column;
          flex-direction: column;
  background: -webkit-gradient(linear, left top, left bottom, from(red), to(blue));
  background: -webkit-linear-gradient(red, blue);
  background: linear-gradient(red, blue);
}

You can also disable visual cascade for CSS prefixes:

{
  "autoprefixer": {"cascade": false}
}

See Autoprefixer on GitHub.

filters

Converts CSS shorthand filters to SVG equivalent, using pleeease-filters.

It converts this file:

.blur {
  filter: blur(4px);
}

To this one:

.blur {
  filter: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg"><filter id="filter"><feGaussianBlur stdDeviation="4" /></filter></svg>#filter');
  -webkit-filter: blur(4px);
          filter: blur(4px);
}

Great combo with Autoprefixer!

You can also force IE filters with an option:

{
  "filters": { "oldIE": true }
}

Using the first example, you'll get:

.blur {
  filter: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg"><filter id="filter"><feGaussianBlur stdDeviation="4" /></filter></svg>#filter');
  -webkit-filter: blur(4px);
          filter: blur(4px);
  filter: progid:DXImageTransform.Microsoft.Blur(pixelradius=4);
}

Then, needed prefixes are added by Autoprefixer. You don't have to care about this.

Be careful, not all browsers support CSS or SVG filters. For your information, latest WebKit browsers support CSS shorthand, Firefox support SVG filters and IE9- support IE filters (limited and slightly degraded). It means that IE10+, Opera Mini and Android browsers have no support at all. Moreover, IE filters shouldn't be used.

rem

Generates pixel fallbacks for rem units, using pixrem. Add options as an array:

• first parameter is the root font-size (default 16px)
• second parameter is an object with:
  • replace if you want to replace value (default false)
  • atrules if you want to replace rem even in at-rules (default false)

{
  "rem": ["16px"]
}

Pixrem converts this file:

.element {
  font-size: 2rem;
}

To this one:

.element {
  font-size: 32px;
  font-size: 2rem;
}

Pixrem don't generates rem fallbacks when browsers without rem support don't understand the property/value (eg in media-queries (all at-rules actually), in properties like transform, border-radius, etc. and in values like calc() or linear-gradient())

Pixrem also tries to read root font-size value from CSS, if defined. This means that:

html { font-size: 20px; }
.a { font-size: 2rem; }

gives

html { font-size: 20px; }
.a { font-size: 40px; font-size: 2rem; }

See pixrem on GitHub.

pseudoElements

Converts pseudo-elements using CSS3 syntax (two-colons notation like ::after, ::before, ::first-line and ::first-letter) with the old one, using only one colon (useful for IE8 support). There are no options.

Converts this file:

.element::after {
  content: '';
}

To this one:

.element:after {
  content: '';
}

opacity

Adds opacity filter for IE8 when using opacity property.

Converts this file:

.element {
  opacity: .5;
}

To this one:

.element {
  opacity: .5;
  filter: alpha(opacity=50);
}

See postcss-opacity on GitHub.

import

Inlines @import styles, using postcss-import and rebases URLs if needed.

You can use the CSS syntax you want:

@import "file.css";
@import url(file.css);
@import url("http://foo.com/bar.css"); /* not imported */
@import url("file.css") screen and (max-width: 35em); /* imported in media-queries */

Note that you can set the "root" folder for imported files with path option, even if this is not the root of your project (default is process.cwd()). For example, if you compile css/foo.css that containing an @import, set options like this:

{
    "import": {"path": "css"}
}

URLs are rebased according to destination file. Configure this by setting out option:

{
    "out": "path/to/destination/file.css"
}

You can also disable URLs rebase.

Important note: In edge cases, this processor may cause unloaded files by browsers. Always check generated CSS and open issue if you encounter problems.

See postcss-import on GitHub.

rebaseUrls

Rebases URLs on @imported files, using postcss-url. Set to false to disable.

minifier

Minifies, using CSS Wring.

mqpacker

Packs same CSS media-queries into one media-query rule, using MQ Packer. There are no options.

Mqpacker can convert multiple files like this:

@media (max-width: 36em) {
  .element {
    color: red;
  }
}

@media (max-width: 36em) {
  .test {
    color: blue;
  }
}

To this one:

@media (max-width: 36em) {
  .element {
    color: red;
  }
  .test {
    color: blue;
  }
}

Important note: In edge cases, this processor can produce unsafe grouping. Always check generated CSS and open issue if you encounter problems.

Sourcemaps

Pleeease generates sourcemaps (disabled by default). Enable them in options:

{
    "sourcemaps": true
}

If you want to have correct sourcemaps, you should always specify in and out files:

{
    "in": "input.css",
    "out": "output.css",
    "sourcemaps": true
}

By default, sourcemaps will be inlined in CSS. If you want separate sourcemaps, you need to set sourcemaps option based on PostCSS documentation:

{
    "in": "input.css",
    "out": "output.css",
    "sourcemaps": {
        "map": {
            "inline": false
        }
    }
}

If you're using CLI tool, two files will be written on disk. With programmatic usage, Pleeease will return an object with css and map properties.

var opts = {
    "in": "input.css",
    "out": "output.css",
    "sourcemaps": {
        "map": {
            "inline": false
        }
    }
};

var fixed = pleeease.process('a{a:a}', opts);

// fixed.css
// fixed.map

If you've activated a preprocessor, no need for more options. You will get sourcemaps from preprocessor.

CLI

With the pleeease-cli package, you can compile files or watch them! The two commands work with a configuration file.

compile

$ pleeease compile

watch

$ pleeease watch

Same as compile, except that the live compilation is activated. When a modification is detected, files will be recompiled automatically.

help

$ pleeease