You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

112 lines
8.1 KiB

  1. # icssify
  2. 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.
  3. Inspired by [postcssify-iss](https://github.com/carlhopf/postcssify-icss), but essentially an entirely new implementation, due to different architectural requirements.
  4. 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.
  5. ## Why use icssify and not ________?
  6. * __[css-loader](https://github.com/webpack-contrib/css-loader):__ This is a Webpack plugin, so it can't be used with Browserify.
  7. * __[css-modulesify](https://github.com/css-modules/css-modulesify):__ Outdated, seemingly no longer maintained, heavily relies on an also-no-longer-maintained 'core' library.
  8. * __[postcssify-icss](https://github.com/carlhopf/postcssify-icss):__ Outdated approach, ICSS imports do not work correctly, `extract-css` not supported.
  9. ## Considerations
  10. 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.
  11. In particular, the following things should be kept in mind:
  12. - 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).
  13. - 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.
  14. 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.
  15. 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).
  16. ## License
  17. 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!
  18. 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.
  19. Any contributions made to this projects are assumed to be dual-licensed under the WTFPL/CC0.
  20. ## Usage examples
  21. Using Babel and `icssify`, and bundling the CSS in with the JS, auto-loading it:
  22. ```
  23. browserify -t [ babelify ] -p [ icssify ] src/index.js > dist/bundle.js
  24. ```
  25. The same, but extracting the CSS into a separate file:
  26. ```
  27. browserify -t [ babelify ] -p [ icssify ] -p [ css-extract -o dist/bundle.css ] src/index.js > dist/bundle.js
  28. ```
  29. Or through the programmatic Browserify API:
  30. ```js
  31. const icssify = require("icssify");
  32. const cssExtract = require("css-extract");
  33. // ... browserify setup code goes here ...
  34. browserifyInstance.plugin(icssify, { before: [ /* your custom PostCSS transforms go here */ ] });
  35. /* And, if you want to extract the CSS, also do: */
  36. browserifyInstance.plugin(cssExtract, { out: "dist/bundle.css" });
  37. // ... more browserify code goes here ...
  38. ```
  39. 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.
  40. ## API
  41. Plugin options (all optional):
  42. * __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" ]`.
  43. * __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.
  44. * __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.
  45. * __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.
  46. * __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.
  47. * __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.
  48. __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.
  49. ## Changelog
  50. ### v2.0.0 (August 23, 2020)
  51. - __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!
  52. - __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.
  53. - __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.
  54. ### v1.2.1 (March 6, 2020)
  55. - __Documentation:__ Fixed missing changelog item for v1.2.0.
  56. ### v1.2.0 (March 6, 2020)
  57. - __Feature:__ You can now specify custom `extensions` that should be treated as CSS files, besides `".css"`.
  58. - __Bug:__ Resolved the "promise not returned" warning from Bluebird when running with warnings enabled.
  59. ### v1.1.1 (February 16, 2020)
  60. - __Bug__:__ Removed stray console.log call.
  61. ### v1.1.0 (February 15, 2020)
  62. - __Improvement:__ Now actually explicitly validates the `options` you specify and gives you a helpful error message, instead of a cryptic one.
  63. ### v1.0.1 (February 15, 2020)
  64. - __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.
  65. - __Bug:__ Fall back to working directory for relative path calculation, when no explicit entry path is specified.
  66. ### v1.0.0 (November 24, 2019)
  67. Initial release.