broccoli-postcss

6.1.0 verified Fri May 01 auth: no javascript maintenance

Broccoli plugin to compile CSS through PostCSS plugins. Current stable version is 6.1.0 (PostCSS 8), compatible with Node >=10. Release cadence is low; last update was 2020. Key differentiators: integrates PostCSS into the Broccoli build pipeline, supports whitelist/blacklist filtering via globs, source map configuration, and two plugin definition styles (object and function forms). Alternative to using PostCSS CLI or other build tool integrations.

Common errors

error Error: Cannot find module 'postcss' ↓

cause postcss is a peer dependency and not installed automatically.

fix

npm install --save-dev postcss

error TypeError: options.plugins[0].module is not a constructor ↓

cause Plugin may be incompatible with PostCSS 8 or not using object form correctly.

fix

Ensure plugins are compatible with PostCSS 8 and use object form: { module: require('plugin'), options: {} }

error ReferenceError: require is not defined ↓

cause Trying to use require() in an ES module context.

fix

Use import or ensure you are using CommonJS (type: 'commonjs' in package.json).

Warnings

breaking Version 6 requires PostCSS 8. PostCSS 8 uses a new plugin API; some plugins may not be compatible. ↓

fix Update all postcss plugins to versions supporting PostCSS 8, or stay on v5 with PostCSS 7.

breaking Node.js >=10 required as of version 6. ↓

fix Upgrade Node.js to version 10 or higher.

deprecated The 'browsers' option is deprecated; use browserslist configuration (package.json or .browserslistrc) instead. ↓

fix Remove 'browsers' from options and set up browserslist in your project.

gotcha Plugins defined in function form cannot have additional options merged (e.g., map). Use object form for extra options. ↓

fix Use object form: { module: require('plugin'), options: { ... } }

gotcha The library is CommonJS only; ES module imports (import) will fail. ↓

fix Use require() instead of import.

Install

npm install broccoli-postcss

yarn add broccoli-postcss

pnpm add broccoli-postcss

Imports

default

wrong

import compileCSS from 'broccoli-postcss'

correct

const compileCSS = require('broccoli-postcss')

Library does not support ES modules; CommonJS only.

default

wrong

const { compileCSS } = require('broccoli-postcss')

correct

const compileCSS = require('broccoli-postcss')

Default export is a function, not a named export.

default (TypeScript)

wrong

import compileCSS from 'broccoli-postcss'

correct

const compileCSS: any = require('broccoli-postcss')

No type definitions available; use any or write own types.

Quickstart

Configures broccoli-postcss with one plugin (postcss-cssnext), sets source maps off, includes styles/*.css, excludes vendor/**/*.

const compileCSS = require('broccoli-postcss');
const cssnext = require('postcss-cssnext');
const options = {
  plugins: [
    {
      module: cssnext,
      options: { browsers: ['last 2 versions'] }
    }
  ],
  map: false,
  include: ['styles/*.css'],
  exclude: ['vendor/**/*']
};
const outputTree = compileCSS('app/styles', options);
module.exports = outputTree;