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.
113 lines
8.1 KiB
Markdown
113 lines
8.1 KiB
Markdown
# 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).
|
|
- 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.
|
|
* __autoExportImports:__ Whether to automatically re-export all imports in a CSS file. When disabled, only *explicitly-defined* class names are exported from a CSS file. Defaults to `true`, ie. all imports are automatically re-exported under their local name.
|
|
* __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.
|
|
* __ignoreCycles:__ When enabling this, `icssify` will handle cyclical dependencies by randomly (but deterministically) ignoring a dependency relation during sorting. This *should* be safe to do for JS files, but there's no guarantee - and if things break in strange ways when you enable this, that is probably why.
|
|
__Cyclical dependencies in CSS files are *still* not allowed__, even when enabling this setting! It's just intended to deal with cyclical JS dependencies during sorting, which are a bad practice but technically valid to have. It's opt-in to ensure that you understand the risks of enabling it.
|
|
|
|
## Changelog
|
|
|
|
### v2.0.0 (August 23, 2020)
|
|
|
|
- __Breaking:__ The CSS transform is now global by default, to better handle cases where CSS in a third-party module needs to be included in the bundle. This *should* not cause any issues, but it's possible that this might break some existing bundling setups unexpectedly, so it's technically a breaking change. Please file an issue if this change causes problems for you!
|
|
- __Feature:__ Added more sensible handling of cyclical dependencies. It will now throw a clear error instead of silently dropping modules on the floor, and gives you the `ignoreCycles` option to continue bundling anyway.
|
|
- __Feature:__ Automatically re-export imported classes. This makes it possible to transparently move a certain class definition to another file, without breaking existing imports. This can be disabled by changing the `autoExportImports` option.
|
|
|
|
### 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.
|