Skip to main content

@roots/bud-postcss

This extension adds PostCSS support.

Installation​

npm install @roots/bud-postcss --save-dev

Usage​

By default, @roots/bud-postcss includes the following plugins, registered with PostCSS in this order:

OrderPlugin
1postcss-import
2postcss-nested
3postcss-preset-env

If this works for you, great! No need to keep reading.

Should you need something more specialized, you can configure PostCSS in your bud config file or a standard PostCSS config file.

Note that by using a PostCSS config file you will be overriding the bud.js options API.

Overriding PostCSS options directly​

You can set the PostCSS options directly using bud.postcss.setPostcssOptions.

It's best to use this method only if you are comfortable with PostCSS and know what you are doing.

bud.postcss.setPostCssOptions({
parser: `sugarss`,
plugins: [`postcss-import`, `postcss-nested`, `postcss-preset-env`],
})

Doing it this way is to-the-point but you are fully overriding the default settings. Other bud.js extensions related to PostCSS will likely not work.

Adding a plugin​

Adding a plugin with the API is a two step process:

  1. Register the plugin
  2. Add it to the plugin order

Let's look at how this is done using tailwindcss as an example.

bud.postcss
/** Register the tailwindcss/nesting plugin */
.setPlugin(`tailwindcss/nesting`)
/** Register the tailwindcss plugin and options */
.setPlugin(`tailwindcss`)
/** Specify which registered plugins you want to use, in the order they should be added */
.use([`import`, `tailwindcss/nesting`, `tailwindcss`, `env`])

Step 1. Registration​

bud.postcss.setPlugin(`example-postcss-plugin`)

If you want to be specific about how to resolve a plugin, you can pass a second parameter.

bud.postcss.setPlugin(
`example-postcss-plugin`,
bud.path(`@modules/example-postcss-plugin/lib/index.js`),
)

If you want to pass along options with the plugin, you can do so by passing an array.

bud.postcss.setPlugin(`example-postcss-plugin`, [
`example-postcss-plugin`,
{stage: 1},
])

Step 2. Add the plugin​

bud.postcss.use([
`postcss-import`,
`postcss-nesting`,
`example-postcss-plugin`, // our new plugin
'postcss-preset-env',
])

You can also use a callback:

bud.postcss.use(plugins => [...plugins, 'example-postcss-plugin'])

Override plugin options​

You can modify options for a plugin using bud.postcss.setPluginOptions.

The first parameter is the plugin key and the second is the options object.

bud.postcss.setPluginOptions('example-postcss-plugin', {optimize: false})

Override plugin path​

You can modify the path for a PostCSS plugin using bud.postcss.setPluginPath.

The first parameter is the plugin key and the second is the new path to assign.

bud.postcss.setPluginPath(
'example-postcss-plugin',
bud.path('./lib/my-plugin.js'),
)

Remove a plugin​

You may remove a plugin by calling bud.postcss.unsetPlugin with the plugin key.

bud.postcss.unsetPlugin(`import`)

Additional options​

OptionTypeDefault
parserstringundefined
sourceMapbooleantrue
syntaxstringundefined

Each option has an associated getter and setter.

bud.postcss.parser​

The parser option is used to specify the parser to use for the PostCSS processor.

bud.postcss.setParser(`postcss-sass`)

bud.postcss.sourceMap​

The sourceMap option is used to specify whether or not to generate a source map.

bud.postcss.setSourceMap(false)

bud.postcss.syntax​

The syntax option is used to specify the syntax to use for the PostCSS processor.

bud.postcss.setSyntax(`sugarss`)