README.md

@metalsmith/postcss

A Metalsmith plugin that sends your CSS through any PostCSS plugins.

Installation

NPM:

npm install @metalsmith/postcss

Yarn:

yarn add @metalsmith/postcss

Note: you need to install postcss and postcss plugins separately

Usage

Add the postcss package name, optionally with its options, to your .use() directives. Here is an example using postcss-pseudoelements and postcss-nested to transform your source files:

import postcss from '@metalsmith/postcss';

// defaults with 2 plugins:
metalsmith.use(postcss({ plugins: {
  'postcss-pseudoelements': {}
  'postcss-nested': {}
}}))

// explicit defaults with 2 plugins:
metalsmith.use(postcss({
  pattern: '**/*.css',
  plugins: {
    'postcss-pseudoelements': {}
    'postcss-nested': {}
  },
  map: false
}));

Options

• pattern {string|string[]} (optional) - Pattern of CSS files to match relative to Metalsmith.source(). Defaults to **/*.css
• plugins {Object|Array<Object|string>} (optional) - An object with PostCSS plugin names as keys and their options as values, or an array of PostCSS plugins as names, eg 'postcss-plugin'or objects in the format { 'postcss-plugin': {...options}}
• map {boolean|{inline:boolean}}*(optional)* - Passtruefor inline sourcemaps, or{ inline: false }` for external source maps
• syntax {string} (optional) - Module name of a PostCSS Syntax or a syntax object itself. Can also be a custom syntax or a relative module path.

By default, files with .css extension will be parsed. This may be overridden by providing a custom pattern e.g.

metalsmith.use(postcss({
  pattern: '*.postcss',
  plugins: { ... }
}));

Alternative plugin definition syntax

Sometimes plugins need to be defined in a certain order and JavaScript Objects cannot guarantee the order of keys in an object. You can also specify PostCSS plugins using an array of objects:

metalsmith.use(
  postcss({
    pattern: '*.postcss',
    plugins: ['postcss-pseudoelements', { 'postcss-nested': { some: 'config' } }]
  })
)

Sourcemaps

This plugin supports generating source maps. To do so, pass map: true for inline source maps (written into the CSS file), or map: { inline: false } for external source maps (written as file.css.map):

metalsmith.use(
  postcss({
    plugins: {},
    map: true // same as { inline: false }
  })
)

Example config for external source maps

metalsmith.use(
  postcss({
    plugins: {},
    map: {
      inline: false
    }
  })
)

Source maps generation is compatible with @metalsmith/sass and will find correct file paths from .scss source all the way through the last PostCSS transforms:

metalsmith
  .use(
    sass({
      entries: {
        'src/index.scss': 'index.css'
      }
    })
  )
  .use(
    postcss({
      map: true
    })
  )

CLI usage

To use this plugin with the Metalsmith CLI, add @metalsmith/postcss to the plugins key in your metalsmith.json file: Here is an example using postcss-pseudoelements and postcss-nested to transform your source files.

{
  "plugins": [
    {
      "@metalsmith/postcss": {
        "plugins": {
          "postcss-pseudoelements": {},
          "postcss-nested": {}
        },
        "map": true
      }
    }
  ]
}

Credits

Thanks to AXA Switzerland for developing the initial versions of this plugin on which this plugin is based.

License

MIT

Test

To run the tests use:

npm test

To view end-to-end tests in browser, use:

npm run test:e2e