@metalsmith/postcss

@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:

const postcss = require('@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

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