npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ember-cli-postcss

v8.2.0

Published

Use postcss to process your css with a large selection of JavaScript plug-ins.

Downloads

159,687

Readme

Installation

ember install ember-cli-postcss

Compatibility

Due to changes in the plugin API of Postcss V8 some plugins will need to be updated after upgrading Postcss. This should be as simple as updating this package from v6 to v7, however compatibility is not guaranteed.

  • V7 ember-cli-postcss -> Postcss V8
  • V6 ember-cli-postcss -> Postcss V7

Usage

The add-on can be used in two ways:

  • on individual files, referred to as “compile”
  • on all CSS files, referred to as “filter”

Note: it’s possible to use both compile and filter.

Additional Note: this app is compatible with Glimmer JS

Compile

This step will look for either app.css or <project-name>.css in your styles directory. Additional files to be processed can be defined in the output paths configuration object for your application:

const app = new EmberApp(defaults, {
  outputPaths: {
    app: {
      html: 'index.html',
      css: {
        'app': '/assets/app.css',
        'print': '/assets/print.css'
      }
    }
  }
}

Filter

This step will run at the end of the build process on all CSS files, including the merged vendor.css file and any CSS imported into the Broccoli tree by add-ons.

Files can be white-listed and/or black-listed by using the respective include and exclude options. Each accepts an array of file globs, which are then passed on to Broccoli Funnel. An example can be seen in the sample configuration below.

Configuring Plug-ins

There are two steps to setting up postcss with ember-cli-postcss:

  1. install and require the node modules for any plug-ins
  2. provide the node module and plug-in options as a postcssOptions object in ember-cli-build.js

The postcssOptions object should have a “compile” and/or “filter” property, which will have the properties enabled and plugins, which is an array of objects that contain a module property and an options property:

Browser Targets

Some postcss plug-ins, like autoprefixer, allow you to configure which browsers to target for transpilation. When using Ember CLI >= 2.13.0, the browser targets configuration found in the file config/targets.js will be added to each plug-in’s options (as options.browsers). This browser list can be overwritten on a plug-in by plug-in basis. You can learn more about the targets feature on the Ember.js blog.

postcssOptions: {
  compile: {
    enabled: true, // defaults to true
    browsers: ['last 3 versions'], // this will override config found in config/targets.js
    plugins: [
      {
        module: <module>,
        options: {
          ...
        }
      }
    ]
  },
  filter: {
    enabled: true, // defaults to false
    map: false, // defaults to inline, false in production
    browsers: ['last 3 versions'], // this will override config found in config/targets.js
    include: ['styles/*.css'],
    exclude: ['vendor/bootstrap/**/*'],
    processTrees: ['css'],
    plugins: [
      {
        module: <module>,
        options: {
          ...
        }
      }
    ]
  }
}

Process Trees

When using the filter version of this add-on the default configuration is now to only run on the css tree. This will mean that the add-on is only run when CSS files are changed. If you need the process to run on other trees or when other files are changed, you should update the processTrees option to include more trees from the following list: [template, js, css, test, all,]

Example

Install the autoprefixer plug-in:

npm i --save-dev autoprefixer

Specify some plug-ins in your ember-cli-build.js:

const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const autoprefixer = require('autoprefixer');

module.exports = function (defaults) {
  const app = new EmberApp(defaults, {
    postcssOptions: {
      compile: {
        enabled: false,
      },
      filter: {
        enabled: true,
        plugins: [
          {
            module: autoprefixer,
            options: {
              browsers: ['last 2 versions'] // this will override the config, but just for this plugin
            }
          }
        ]
      }
    }
  });
  return app.toTree();
};

Compile Caching

When using the compile method, the default list of file extensions for caching is set to .css, .scss, .sass, .less for faster incremental builds. If you are using a parser or filetype not in the list you will want to add the file extension as a regex to the cacheInclude option.

If you are using something like Tailwind or a postcss plugin with a JS config file that you would like to trigger a rebuild, you will need to update the options to cache JS files: cacheInclude: [/.*\.(css|scss|sass|less|js)$/], or more specifically cacheInclude: [/.*\.(css|scss)$/, /.tailwind\.js$/].

If you are using something like PurgeCSS and would like postcss to rebuild when template files are updated, you will need to update the options to cache HBS files: cacheInclude: [/.*\.(css|scss|sass|less|hbs)$/],. However, in most cases PurgeCSS should only be run for a production build and this shouldn't be necessary.

Example

postcssOptions: {
  compile: {
    enabled: true,
    cacheExclude: [],
    cacheInclude: [/.*\.(css|scss|sass|less)$/]
  }
}

Developing Addons

If you are developing an addon and would like to use ember-cli-postcss to process the CSS to automatically be included in the vendor.css of Ember applications consuming the addon, there are 3 steps to follow.

  1. create your styles in addon/styles/addon.css (you can import other CSS files if a postcss import plugin is installed)
  2. Add a "before" option under ember-addon key in package.json
// package.json
  ...
  "ember-addon": {
    "before": [
      "ember-cli-postcss"
    ],
    "configPath": "tests/dummy/config"
  },
  ...
  1. configure your addon’s options to process postcss:
// index.js
const CssImport = require('postcss-import')
const PresetEnv = require('postcss-preset-env');

module.exports = {
  name: require('./package').name,
  included: function(app) {
    this._super.included.apply(this, arguments);
    app.options = app.options || {};
    app.options.postcssOptions = {
      compile: {
        enabled: true,
        plugins: [
          { module: CssImport },
          {
            module: PresetEnv,
            options: { stage: 3 }
          }
        ]
      }
    }
  },
  ...
};

Migrating from other Processors

If you’d like to migrate a project from one of the other processors, such as Less, Sass, or Stylus, you can configure Postcss with an appropriate parser and set of plugins that provides an equivalent set of features.

This then allows you to use additional Postcss plugins at the end of the compilation to continue transforming your styles for more powerful control of authoring styles in your application. This also plays nicely with ember-component-css.

So far this migration process has been tested when switching from Sass.

Switching from Sass

One common use case is to transition from using Sass to Postcss or using them both together. As of [email protected] this is possible with the right combination of options and plugins.

There are three key pieces of configuration:

  1. Set the parser to postcss-scss
  2. Configure the extension to match your files (ie. 'scss')
  3. Use @csstools/postcss-sass as the first plugin

Your configuration options in ember-cli-build.js would contain the following options for this addon:

  postcssOptions: {
    compile: {
      extension: 'scss',
      enabled: true,
      parser: require('postcss-scss'),
      plugins: [
        {
          module: require('@csstools/postcss-sass'),
          options: {
            includePaths: [
              'node_modules/tachyons-sass',
            ],
          },
        },
        ...
      ],
    },
    ...
  }

This allows your to switch your CSS processing pipeline to use postcss without being hugely disruptive as you can keep the Sass features and .scss or .sass file extension. The importing feature of @csstools/postcss-sass will also look for .css files, so you can choose to gradually rename your files from Sass partials _<filename>.scss to <filename>.css without breaking anything.

If your goal is to completely move away from using Sass features you can remove the parser, remove the sass plugin, use an import plugin that fits your needs and ensure that your files have the .css extension.

Experimental Features

Custom Properties Service

CSS variables are now supported by many major browsers. The values of these variables can be accessed, set, and removed using JavaScript. This addon now exports a service, which provides methods to work with CSS variables. Each method is a wrapper around the browser API, which includes a check for browser support before executing.

The service provides 3 methods:

  1. getVal ({ element = docEl, variableName })
  2. setVal ({ element = docEl, variableName, variableValue })
  3. removeVal ({ element = docEl, variableName })

A Contrived Example:

import { inject } from '@ember/service'

export default <ember object>.extend({
  customProperties: inject(),
  ...

  nightMode() {
    this.get('customProperties').setVal({variableName: '--background', variableValue: 'black'})
    this.get('customProperties').setVal({variableName: '--text', variableValue: 'white'})
  },

  dayMode() {
    this.get('customProperties').setVal({variableName: '--background', variableValue: 'white'})
    this.get('customProperties').setVal({variableName: '--text', variableValue: 'black'})
  },
})

Note: if you are using postcss-custom-properties, ensure you configure the option { preserve: true }