icssify/README.md

# icssify

A Browserify plugin for handling CSS (through PostCSS), with **full and correct support** for [ICSS](https://github.com/css-modules/icss) and [CSS modules](https://github.com/css-modules/css-modules/blob/master/README.md). Works with `css-extract`. Allows specifying custom PostCSS transforms.

Inspired by [postcssify-iss](https://github.com/carlhopf/postcssify-icss), but essentially an entirely new implementation, due to different architectural requirements.

The `index.js` file in this module's repository contains inline documentation on how the plugin works. If you're looking to implement your own ICSS / CSS modules implementation for another bundler (or just want to know how this one works!), it may be useful to give it a read.

## Why use icssify and not ________?

* __[css-loader](https://github.com/webpack-contrib/css-loader):__ This is a Webpack plugin, so it can't be used with Browserify.
* __[css-modulesify](https://github.com/css-modules/css-modulesify):__ Outdated, seemingly no longer maintained, heavily relies on an also-no-longer-maintained 'core' library.
* __[postcssify-icss](https://github.com/carlhopf/postcssify-icss):__ Outdated approach, ICSS imports do not work correctly, `extract-css` not supported.

## Considerations

This plugin changes quite a few things in the Browserify pipeline to make CSS work correctly, and it tries to make those changes as unobtrusively as possible. However, due to design limitations in Browserify, it's *not guaranteed* that this plugin will work together with other Browserify plugins.

In particular, the following things should be kept in mind:

- This plugin changes Browserify's sorting algorithm, so that files are always processed in 'dependency order'. While this *shouldn't* be an issue because the new algorithm is deterministic just like the old one, it's possible for a different plugin to break this one, if it changes the sorting algorithm. To prevent this, always load `icssify` __last__ (but still before `watchify` and `css-extract`, if you're using those).
- The sorting algorithm cannot currently deal with circular dependencies. __Trying to use this plugin will break, when you have circular dependencies.__ You really shouldn't have those, but this is still worth keeping in mind. PRs to fix this are welcome.
- CSS files are not JS files. This plugin sneaks the CSS past Browserify's syntax checker, but it will still send CSS files through the pipeline. Plugins that operate on JS *must* ignore non-JS files, otherwise they will break.

This plugin will always bundle all CSS __into a single file__. For complexity reasons, there is currently no support for splitting up CSS into multiple bundles. PRs that add support for this (without breaking ICSS or `css-extract` support!) are welcome.

By default, this plugin will use `insert-css` to automatically load the bundled CSS into the browser when any part of it is `require()`d. If you want to serve the CSS as a separate file, rather than as a part of the bundle, use [`css-extract`](https://www.npmjs.com/package/css-extract).

## License

Most of this library is licensed under the [WTFPL](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), at your choice. This basically means you can treat it as public domain, and use it in any way you want. Attribution is appreciated, but not required!

Some parts (namely, the PostCSS plugins) are derived from `css-loader`, and are therefore under the [MIT](https://opensource.org/licenses/MIT) license. The affected files contain a licensing header saying so.

Any contributions made to this projects are assumed to be dual-licensed under the WTFPL/CC0.

## Usage examples

Using Babel and `icssify`, and bundling the CSS in with the JS, auto-loading it:

```
browserify -t [ babelify ] -p [ icssify ] src/index.js > dist/bundle.js
```

The same, but extracting the CSS into a separate file:

```
browserify -t [ babelify ] -p [ icssify ] -p [ css-extract -o dist/bundle.css ] src/index.js > dist/bundle.js
```

Or through the programmatic Browserify API:

```js
const icssify = require("icssify");
const cssExtract = require("css-extract");

// ... browserify setup code goes here ...

browserifyInstance.plugin(icssify, { before: [ /* your custom PostCSS transforms go here */ ] });

/* And, if you want to extract the CSS, also do: */
browserifyInstance.plugin(cssExtract, { out: "dist/bundle.css" });

// ... more browserify code goes here ...
```

For further usage examples, refer to the usual Browserify documentation. `icssify` is just a plugin like any other, and shouldn't require special handling, other than what's listed in the "considerations" section above.

## API

Plugin options (all optional):

* __extensions:__ An array of extensions (without the leading dot!) that should be considered "CSS files"; this is useful when you eg. name your files `.postcss` to indicate that you are using non-standard syntax. This list of extensions will *replace* the default list of extensions, so you will need to explicitly specify `"css"` in the list, if you want to keep parsing `.css` files. Defaults to `[ "css" ]`.
* __mode:__ Whether to assume that untagged class names in your CSS (ie. those without a `:local` or `:global` tag) are local or global. Defaults to `"local"`, but you can set this to `"global"` if you want to make the class name mangling *opt-in*. You'll generally want to leave this at the default setting.
* __before:__ PostCSS transforms to run *before* the ICSS transforms, ie. before imports/exports are analyzed. This is usually where you want custom PostCSS plugins to go.
* __after:__ PostCSS transforms to run *after* the ICSS transforms, ie. after mangling the class names, but before bundling it all together into a single file. You'll rarely need to use this.


## Changelog

### v1.2.1 (March 6, 2020)

- __Documentation:__ Fixed missing changelog item for v1.2.0.

### v1.2.0 (March 6, 2020)

- __Feature:__ You can now specify custom `extensions` that should be treated as CSS files, besides `".css"`.
- __Bug:__ Resolved the "promise not returned" warning from Bluebird when running with warnings enabled.

### v1.1.1 (February 16, 2020)

- __Bug__:__ Removed stray console.log call.

### v1.1.0 (February 15, 2020)

- __Improvement:__ Now actually explicitly validates the `options` you specify and gives you a helpful error message, instead of a cryptic one.

### v1.0.1 (February 15, 2020)

- __Bug:__ Don't break when an upstream transform erroneously produces a Buffer while claiming it to be `encoding: "utf8"`, by ignoring the `encoding` parameter entirely.
- __Bug:__ Fall back to working directory for relative path calculation, when no explicit entry path is specified.

### v1.0.0 (November 24, 2019)

Initial release.