@roots/bud-postcss

This extension adds PostCSS support.

Installation

npm

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

Yarn

yarn add @roots/bud-postcss --dev

pnpm

pnpm add @roots/bud-postcss --save-dev

Usage

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

Order	Plugin
1	postcss-import
2	postcss-nested
3	postcss-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.config.ts

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.config.ts

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.config.ts

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.config.ts

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.config.ts

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

Step 2. Add the plugin

bud.config.ts

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

You can also use a callback:

bud.config.ts

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.config.ts

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.config.ts

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.config.ts

bud.postcss.unsetPlugin(`import`)

Additional options

Option	Type	Default
parser	string	undefined
sourceMap	boolean	true
syntax	string	undefined

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`)