Documentation

Detailed explanations of the configuration options for advanced usage of the addon.

Overview

There are many ways to configure Postcss with your app or addon. This documentation serves as an explanation for the different types of stylesheet processing and a reference for all the available options.

Currently, this addon only affects the build step of your application. Other functionality is planned, but not yet released.

Compile vs. Filter

One source of confusion when using this addon is figuring out which of the modes to use and why the two are configurable separately.

These two options exist due to how ember-cli processes an application and the hooks it makes available. You can only use one CSS processor to compile your styles because it uses the toTree hook of an Ember Addon, which transforms your styles, and in many cases, removes it from the tree of available files and then writing a corresponding CSS file to the tree. An example would be if you're using Sass this step would remove app-name.scss from the tree and after processing write app-name.css.

With this in mind, the general rule is that if you would like to use Postcss as your main processor for your stylesheets, use compile and if you would like to run Postcss after another processor or on all of your styles, including files added by addons or through vendor, then use filter.

All Available Options

Compile

type: object default: see below

An options object to be passed to the broccoli-postcss-single compiler.

enabled

type: boolean default: true

Controls if this stage of the processing is run.

map

type: boolean | string | object default: "inline" and false in production

The options that are passed to postcss via broccoli-postcss-single as to how source maps should be rendered.

browsers

type: array default: []

This should be a valid list of browsers to share between plugins. If your app has a targets.js config file they will be pulled from there. Specifying this option will override the config file.

parser

type: function default: undefined

This is an optional setting allowing you to specify a custom parsers, different than the default Postcss parser. Use this if you’d like to parse a different syntax, such as Sass or Sugarcss, by passing in a custom function or node module reference.

extension

type: string default: "css"

Use this option if your main application stylesheet is using an extension other than css.

plugins

type: array default: []

A list of Postcss plugins to be applied to the stylesheets defined in your applications outputPaths.

There are two supported methods for defining plugins:

  1. 1. Object form 
    plugins: [
    {
      module: require('some-plugin'),
      options: { /* options for `some-plugin` */ }
    }
  ]
  2. 2. Function form 
    plugins: [
    require('some-plugin')({ /* options for `some-plugin` */ }),
    require('another-plugin')({ /* options for `another-plugin` */ }),
  ]

Filter

type: object default: see below

An options object to be passed to the broccoli-postcss processor.

Please note, these options are passed on to each plugin and merged with the options defined in the plugins array. In many cases, such as browser targets, this allows them to be defined in one place.

enabled

type: boolean default: false

Controls if this stage of the processing is run.

map

type: boolean | string | object default: "inline"

The options that are passed to postcss via broccoli-postcss-single as to how source maps should be rendered.

include

type: array default: []

Array of GlobStrings|RegExps|Functions to describe a whitelist of files to get processed by Postcss.

exclude

type: array default: []

Array of GlobStrings|RegExps|Functions to describe a blacklist of files to be ignored by Postcss.

browsers

type: array default: []

This should be a valid list of browsers to share between plugins. If your app has a targets.js config file they will be pulled from there. Specifying this option will override the config file.

plugins

type: array default: []

A list of Postcss plugins to be applied to the stylesheets defined in your applications outputPaths.

There are two supported methods for defining plugins:

  1. 1. Object form 
    plugins: [
    {
      module: require('some-plugin'),
      options: { /* options for `some-plugin` */ }
    }
  ]
  2. 2. Function form 
    plugins: [
    require('some-plugin')({ /* options for `some-plugin` */ }),
    require('another-plugin')({ /* options for `another-plugin` */ }),
  ]

Tips

Some thoughts on considerations when using Postcss with an Ember app.

  • Plugin order matters. The styles will be processed through the plugins in the order they are defined. As an example, you'll want to run postcss-import first if you're importing other files.
  • Try to avoid using plugins in compile and filter. With plugins like autoprefixer, you can use it with the filter step and it will apply to all stylesheets, including those added to your vendor styles. This works great in combination with a targets.js configuration for browsers.