@joblift/babel-plugin-transform-postcss/README.md

PostCSS Babel Transform

# - FORKED -

This is a fork from https://github.com/wbyoung/babel-plugin-transform-postcss, which seems currently unmaintained. Why? We needed to update dependencies and include the latest unpublished fixes from that library. Fork updates include:

- supports PostCss 7.x
- supports post-css-loader 2.x
- supports other filename extensions, e.g. \*.scss

Thanks to the original authors. Have fun.

# Babel PostCSS Transform

A [Babel][babel] plugin to process CSS files via [PostCSS][postcss].

Using [PostCSS Modules][postcss-modules], it can transform:

```js
import styles from "./styles";
```

```css
.example {
  color: cyan;
}
```

Into an object that has properties mirroring the style names:

```js
var styles = { example: "_example_amfqe_1" };
```

## Configuration

Install the transform as well as `postcss` and any PostCSS plugins you want to
use:

```bash
# using yarn
yarn add -D @joblift/babel-plugin-transform-postcss
# using npm
npm install --save-dev @joblift/babel-plugin-transform-postcss
```

Add the transform to your babel configuration, i.e. `.babelrc`:

```json
{
  "presets": [["env", { "targets": { "node": "current" } }]],
  "plugins": ["transform-postcss"]
}
```

Create a [`postcss.config.js`][postcss-load-config]:

```js
module.exports = (ctx) => ({
  plugins: [
    require("postcss-modules")({
      getJSON: ctx.extractModules || (() => {}),
    }),
  ],
});
```

You can also specify a location to load your `postcss.config.js` from in the options in your Babel configuration, i.e. `.babelrc`:

```json
{
  "plugins": [
    [
      "transform-postcss",
      {
        "config": "configuration/postcss.config.js"
      }
    ]
  ]
}
```

By default we look for `.css` files, but you can also specify the extensions we should look for:

```json
{
  "plugins": [
    [
      "transform-postcss",
      {
        "config": "configuration/postcss.config.js",
        "extensions": [".scss"]
      }
    ]
  ]
}
```

## Details

The transform will transform all imports & require statements that have a `.css`
extension and run them through `postcss`. To determine the PostCSS config, it
uses [`postcss-load-config`][postcss-load-config] with
[additional context values](#postcss-load-config-context). One of those config
values, [`extractModules`](#extractmodules_-any-modules-object) should be
invoked in order to define the value of the resulting import.

No CSS is actually included in the resulting JavaScript. It is expected that you
transform your CSS using the same `postcss.config.js` file as the one used by
this transform. We recommend:

- [`postcss-cli`][postcss-cli] (v3 or later)
- [`gulp-postcsssrc`][gulp-postcssrc]

Finally, it's worth noting that this transform also adds a comment to the
generated code indicating the related CSS file so that it can be processed by
other tools, i.e. [`relateify`][relateify].

### PostCSS Load Config Context

#### `extractModules(_: any, modules: object)`

This option is a function that may be passed directly on to
[`postcss-modules`][postcss-modules] as the [`getJSON`
argument][postcss-modules-get-json]. Other uses, while unlikely, are
permittable, as well.

The function accepts two arguments. The transform uses only the
second value passed to the function. That value is the object value that
replaces the `import`/`require`.

## Using with Browserify & Watchify

This will work well with the [`babelify`][babelify] transform, but if you're
using [`watchify`][watchify], you will want to add the [`relateify`][relateify]
transform in order to ensure that changes to CSS files rebuild the appropriate
JS files.

## Caching

This module caches the results of the compilation of CSS files and stores the
cache in a directory under `/tmp/bptp-UNIQUE_ID`. The cache is only invalidated
when the CSS file contents change and not when the `postcss.config.js` file
changes (due to limitations at the time of implementation). Try removing the
cache if you're not seeing expected changes.

## Prior Art

This plugin is based of the work of:

- [`css-modules-transform`][css-modules-transform]
- [`css-modules-require-hook`][css-modules-require-hook]

Unlike the above, it supports both synchronous and asynchronous PostCSS plugins.

## License

This project is distributed under the MIT license.

[babel]: https://babeljs.io/
[postcss]: http://postcss.org/
[postcss-cli]: https://github.com/postcss/postcss-cli
[postcss-modules]: https://github.com/css-modules/postcss-modules
[postcss-modules-get-json]: https://github.com/css-modules/postcss-modules#saving-exported-classes
[postcss-load-config]: https://github.com/michael-ciniawsky/postcss-load-config
[css-modules-transform]: https://github.com/michalkvasnicak/babel-plugin-css-modules-transform
[css-modules-require-hook]: https://github.com/css-modules/css-modules-require-hook
[gulp-postcssrc]: https://github.com/michael-ciniawsky/gulp-postcssrc
[babelify]: https://github.com/babel/babelify
[watchify]: https://github.com/substack/watchify
[relateify]: https://github.com/wbyoung/relateify
[travis-image]: http://img.shields.io/travis/wbyoung/babel-plugin-transform-postcss.svg?style=flat
[travis-url]: http://travis-ci.org/wbyoung/babel-plugin-transform-postcss
[npm-image]: http://img.shields.io/npm/v/babel-plugin-transform-postcss.svg?style=flat
[npm-url]: https://npmjs.org/package/babel-plugin-transform-postcss
[coverage-image]: http://img.shields.io/coveralls/wbyoung/babel-plugin-transform-postcss.svg?style=flat
[coverage-url]: https://coveralls.io/r/wbyoung/babel-plugin-transform-postcss
[david-image]: http://img.shields.io/david/wbyoung/babel-plugin-transform-postcss.svg?style=flat
[david-url]: https://david-dm.org/wbyoung/babel-plugin-transform-postcss
[david-dev-image]: http://img.shields.io/david/dev/wbyoung/babel-plugin-transform-postcss.svg?style=flat
[david-dev-url]: https://david-dm.org/wbyoung/babel-plugin-transform-postcss#info=devDependencies