|
3 months ago | |
---|---|---|
src | 3 months ago | |
.eslintrc | 1 year ago | |
.gitignore | 1 year ago | |
README.md | 3 months ago | |
global-css-loader.js | 1 year ago | |
index.js | 6 months ago | |
notes.md | 3 months ago | |
package.json | 3 months ago |
A Browserify plugin for handling CSS (through PostCSS), with full and correct support for ICSS and CSS modules. Works with css-extract
. Allows specifying custom PostCSS transforms.
Inspired by postcssify-iss, 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.
extract-css
not supported.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:
icssify
last (but still before watchify
and css-extract
, if you're using those).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
.
Most of this library is licensed under the WTFPL or CC0, 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 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.
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:
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.
Plugin options (all optional):
.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" ]
.: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.true
, ie. all imports are automatically re-exported under their local name.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.ignoreCycles
option to continue bundling anyway.autoExportImports
option.extensions
that should be treated as CSS files, besides ".css"
.options
you specify and gives you a helpful error message, instead of a cryptic one.encoding: "utf8"
, by ignoring the encoding
parameter entirely.Initial release.