You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
82 lines
5.4 KiB
Markdown
82 lines
5.4 KiB
Markdown
5 years ago
|
# 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):
|
||
|
|
||
|
* __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.0.0 (November 24, 2019)
|
||
|
|
||
|
Initial release.
|