Atomic CSS - Reusable front-end styling using Rework, plugins, and Node's resolve algorithm
atomify-css extends Node's well established practice of creating small, reusable modules to CSS by allowing npm (and other) modules to include style data as part of their packages. Basically, it makes
@import work like
require()(e.g. named modules)
require()for LESS files.
In its default form, atomify-css takes an
opts object and a
While you may use atomify-css with CSS or LESS, you cannot combine them in the same workflow. The workaround for this limitation is to preprocess everything to CSS before passing to atomify-css.
opts.entry or opts.entries - Path or paths that will be provided to Rework as the entry point. For convenience, you may simply provide a string in place of the
opts object, which will be treated as the
entry property. The path will be resolved relative to
opts.transform - A synchronous transformation function that will be run as the final processing step. String in, string out.
opts.output - If you simply want your bundle written out to a file, provide the path in this property. Note that your
callback will NOT be called if this property is present. Path will be resolved relative to
opts.variables - An object hash or a JSON file path that will be provided to rework-vars to replace any vars defined in your CSS.
opts.plugins - An array of Rework plugins to
use() in addition to the defaults listed above.
opts.debug or opts.sourcemap - Passed to the
toString() method of Rework to generate source maps if
true. Also provides additional CLI output, if applicable.
opts.autoprefixer - Accepts all options objects that can be passed to autoprefixer. Set to any truthy value to enable autoprefixer.
opts.compress - Compress (remove whitespace from) CSS output.
opts.assets - One of the challenges with writing truly modular code is that your stylesheets often refer to assets that need to be accessible from your final bundle. Configuring this option solves that problem by detecting asset paths in your CSS files, copying the assets to a new location, and rewriting the references to them to use the new paths. Paths in
url() statements will be processed according to your configuration.
The processing is configured using two sub-properties of opts.assets:
dest field determines the location files will be copied to, relative to
prefix specifies what will be prepended to the new file names in the rewritten
url() calls. The filenames are generated from a hash of the assets themselves, so you don't have to worry about name collisions.
To demonstrate, see the following example.
// configentry: './entry.css'output: 'dist/bundle.css'...assets:dest: 'dist/assets'prefix: 'assets/'
and a copy of background.jpg will now exist at
opts object is passed to the
toCSS() method of the LESS Parser, so any options it supports can be used.
Standard bundle callback with
cb(err, src) signature. Not called if
opts.output is specifed. If
callback is provided as a string rather than function reference it will be used as the
opts.output file path.
Configuring atomify in package.json is pretty straightforward, but there is a bit of nuance in how you specify custom Rework plugins. There are a few different ways plugins can be instantiated, depending on the author's preference, but we support them all in a pretty straightforward manner.
We have essentially implemented the transformKey syntax from module-deps, meaning plugin configuration closely mimics transform configuration in Browserify. The following list shows how keys in your
atomify.css.plugins array will be mapped to code.
["rework-plugin-inline", "src/assets"]maps to
In plain English, a string will simply be passed to
require(), while an array will pass the first element to
require() and call the resulting function with any remaining elements from the array.
/* entry.css */;;;
// build.jsvar css =var opts =entry: './entry.css'debug: true // default: `false`
var css =
npm install atomify-css