icssify

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.

Why use icssify and not ________?

• css-loader: This is a Webpack plugin, so it can't be used with Browserify.
• css-modulesify: Outdated, seemingly no longer maintained, heavily relies on an also-no-longer-maintained 'core' library.
• 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.

License

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.

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:

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.