@ -19,6 +19,7 @@ This plugin changes quite a few things in the Browserify pipeline to make CSS wo
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.
@ -71,20 +72,11 @@ 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 (April 25, 2022)
- __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.
- __Feature:__ icssify now uses PostCSS 8+, and therefore supports plugins in the new format.
// FIXME: When there's >1 icssify instance set up on the Browserify instance (can this happen when a module specifies its own dependency on icssify?), either throw an error (if incompatible?) or merge the two somehow, so that there's only one resulting .css file
// NOTE: This is global because otherwise the transform will not run when processing node_modules. If this causes problems for you, please file an issue!
// FIXME: Figure out if there's a better solution for this
// We want to prevent findCycle from discovering and traversing any nodes that are not in our "conflict set"; otherwise a second pass will fail, because it will rediscover already-handled nodes (that have been removed from the queue) indirectly, and endlessly loop on discovering that cycle.
// ... or, if no entry file is specified, go off the current working directory
@ -28,22 +27,17 @@ module.exports = function (state) {
returnstream((item)=>{
// And the same for the loader shim path. All this relative-path stuff is to prevent absolute filesystem URLs from leaking into the output, as those might contain sensitive information.
// NOTE: This is a workaround, until we find a more robust solution to this. While composed classes should be delimited by dots in CSS, they should be delimited by *spaces* in HTML. In "double compose" cases, ie. when one class composes another class which was already composed with a third class, we can get a class string like "foo bar.baz" which is wrong; this replaces all the erroneous dots with spaces.
// FIXME: Can occur if some dependency also gets processed and require()s a CSS file, but does not specify icssify as a transform (but the using project does) -- like with ui-lib + site-builder
thrownewError("Processed CSS, but global loader was not encountered. This should never happen, please report it as a bug!");
// TODO: Disallow cycles for extensions processed by icssify, *even* when this option is active, because cycles just aren't (sensibly) possible in ICSS
// TODO: Debug-log removed edges here, and the full cycle, to debug potential future infinite recursion bugs
// We will keep throwing out more (deterministically) random edges until we're left with no cycles. If there are enough cycles to cause an exceeded stack size here, you probably have bigger issues to worry about...
f0x