icss-register

A @babel/register-like hook for .css files, so that you can use CSS Modules and ICSS in Electron and other environments, without needing a bundler. Fully supports composition and imports, both in CSS and JS.

Note that "CSS Modules" are really just the JS side of the ICSS specification, so while this documentation talks about "ICSS" which is the underlying system, it also always includes CSS Modules support!

Uses PostCSS 8+, so any custom PostCSS plugins will need to be compatible with that.

This module uses insert-css to actually insert the stylesheets into your document, so it will only work in environments that are supported by it. This includes Electron, and any other environment that provides the usual browser APIs - though it's debatable how useful this module would be in an actual browser, given that you'd normally want to use a bundler there.

License, donations, and other boilerplate

Licensed under either the WTFPL or CC0, at your choice. In practice, that means it's more or less public domain, and you can do whatever you want with it. Giving credit is not required, but still very much appreciated! I'd love to hear from you if this module was useful to you.

Creating and maintaining open-source modules is a lot of work. A donation is also not required, but much appreciated! You can donate here.

Example

In its simplest form, with default settings, just put this before any of your other code or imports:

require("icss-register")();

... or, with custom options:

require("icss-register")({
	before: [ someCustomPostCSSPlugin() ]
});

You can also load and invoke separately, of course:

const icssRegister = require("icss-register");
icssRegister(/* ... options here ... */);

API

let unregister = icssRegister(options)

Sets up the ICSS handling hook.

• options: Optional.
  • mode: Optional. Whether classes that aren't explicitly scoped should be treated as local or global classes. Default is local, which is usually what you want for CSS Modules.
  • autoExportImports: Optional. Whether ICSS-imported identifiers imported into a CSS file are also automatically re-exported from it. Defaults to true, which is usually what you want.
  • extensions: Optional. An array of extensions (including the leading dot) that you want the hook to apply to. This defaults to [ ".css" ], and this setting will override that default, so you should make sure to include .css in your custom array if you want it to keep applying.
  • generateScopedName: Optional. A custom (synchronous) callback for generating a 'mangled' name for a class. You won't usually need this - the default callback for this already prevents name collisions. See the postcss-icss-parser documentation for details on the callback's API.
  • before: Optional. An array of custom PostCSS plugins to apply before handling ICSS imports and exports. This is usually where your custom PostCSS plugins should go.
  • after: Optional. Like before, but for plugins that should run after handling ICSS. Don't use this unless you understand exactly why you need it, as its behaviour will be different from bundler implementations like icssify!
  • postcssOptions: Optional. Any custom ProcessOptions that you want to pass to PostCSS. You don't need to set from, as register-icss will do this for you internally, but you can override it from here.

unregister()

Removes the ICSS handling hook, essentially disabling the module.

Changelog

v1.1.0 (February 17, 2021)

• No longer ignores CSS imports in node_modules

v1.0.0 (February 17, 2021)

• Now actually properly validates arguments, with useful error messages.

v0.1.0 (February 17, 2021)

Initial release.