atomify-css

Atomic CSS - Reusable front-end styling using Rework, plugins, and Node's resolve algorithm

npm install atomify-css
68 downloads in the last week
127 downloads in the last month

atomify-css

Atomic CSS - Reusable front-end styling using Rework, plugins, and Node's resolve algorithm

Description

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().

Using Rework for CSS and less for LESS, atomify-css brings a dependency graph to your CSS.

Default plugins

  • rework-npm - Brings Node's resolve behavior to CSS, making @import work like require() (e.g. named modules)
  • rework-vars - Provides W3C-style CSS variables syntax for CSS files
  • npm-less - Adds support for Node-style resolution, making @import work like require() for LESS files.
  • node-sass - Adds basic SASS support.

API

In its default form, atomify-css takes an opts object and a callback function.

While you may use atomify-css with CSS, LESS, or SASS, there are some limitations to how you can combine them. atomify-css determines which technology you are using based on the file extension of your entry file. At this time the only mixing supported is that the SASS workflow can @import plain CSS files.

The workaround for this limitation is to preprocess everything to CSS before passing to atomify-css.

opts

opts.entry - Path 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 process.cwd().

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 process.cwd().

opts for CSS workflows

opts.variables - An object hash 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.compress - Compress (remove whitespace from) CSS output.

opts for LESS workflows

The entire opts object is passed to the toCSS() method of the LESS Parser, so any options it supports can be used.

callback

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.

package.json config

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-default-unit" maps to require('rework-default-unit')
  • ["rework-clone"] maps to require('rework-clone')()
  • ["rework-plugin-inline", "src/assets"] maps to require('rework-plugin-inline')('src/assets')

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.

Examples

/* entry.css */

@import "./global.css";
@import "./inputs.css";
@import "auth-form";

body {
  background: var(bg);
}
// build.js
var css = require('atomify-css')

var opts = {
  entry: './entry.css'
, debug: true // default: `false`
}

css(opts, function (err, src) {
  // do something with the src
})

OR

var css = require('atomify-css')

css('./entry.css', './bundle.css')

Install

npm install atomify-css
npm loves you