grunt-atomizer

Overview

A grunt task for running Atomizer

Install

npm install grunt-atomizer --save-dev

Usage

Options

None of the options are required. Make sure you understand atomic configs in order to properly use the config options below.

options.cache

Caches the output of the task target by saving it to .atomic-cache at the root dir. False by default.

options.config

The Atomizer config passed directly to the grunt task. See examples below.

options.configFile

The Atomizer config passed as a file. This option can be used as an alternative to options.config or in conjunction with it. See examples below.

options.configOutput

The config file generated by the tool. Useful when parsing is used (See files.src below) and you want to save generated config.

options.bumpMQ

Boolean flag that adds a small amount of additional specificity weight to all media queries. False by default.

options.namespace

A CSS selector used to define scope for the Atomic CSS rules. (eg, if options.namespace is set to #atomic, the CSS output will be in the form of #atomic .P(10px), etc.)

options.rtl

Process the rules for right-to-left output. False by default.

options.rules

An array of additional Atomizer rulesets passed as file paths.

files.src

Any files matched by files.src will be parsed and if valid atomic classes are found they will be added to the final CSS. You'd generally want to also pass a options.configOutput so that you have the updated config. Custom class names cannot be automatically generated and have to be manually added in the config.

files.dest

The path to the CSS file that will be created.

Examples

atomizer: {
    // Example 1: Simple usage. Parse files and create CSS.
    // Ideally you'd also want to pass a namespace to deal with specificity.
    example1: {
        files: [
            {
                src: ['test/fixtures/*.html'],
                dest: 'tmp/configFileOnly.css'
            }
        ]
    },
    // Example 2: Passing a configFile only.
    example2: {
        options: {
            namespace: '#atomic',
            configFile: 'test/fixtures/sample-config.js'
        },
        files: [
            {
                dest: 'tmp/configFileOnly.css'
            }
        ]
    },
    // Example 3: Passing the config to the grunt task directly
    example3: {
        options: {
            namespace: '#atomic',
            config: {
                classNames: ['D(ib)']
            }
        },
        files: [
            {
                dest: 'tmp/configGruntOnly.css'
            }
        ]
    },
    // Example 4: Using both config and configFile.
    // `options.config` will be merged (and override) the `options.configFile`.
    example4: {
        options: {
            namespace: '#atomic',
            // bring a sample config file
            configFile: 'test/fixtures/sample-config.js',
            // config will override any thing declared in configFile
            config: {
                classNames: ['D(ib)'],
                custom: {
                    '1': '10px solid #ccc'
                }
            }
        },
        files: [
            {
                dest: 'tmp/configBoth.css'
            }
        ]
    },
    // Example 5: Using config, configFile and also parsing HTML files (it can be any type of file).
    // Parsing will warn if you've used a class that cannot be automatically generated and therefore requires you to manually add it to the config.
    example5: {
        options: {
            namespace: '#atomic',
            // pass a base config file
            configFile: 'test/fixtures/sample-config.js',
            // override classNames in the base config file
            config: {
                classNames: ['D(b)']
            }
            // the final config file used by the tool will be written
            // in the following file:
            configOutput: 'tmp/configOutput.json',
        },
        files: [
            {
                // parse html files to automatically create a config
                src: ['test/fixtures/*.html'],
                // generate the css in the file below
                dest: 'tmp/configBothWithParsing.css'
            }
        ]
    }
}

License

This software is free to use under the Yahoo! Inc. BSD license. See the LICENSE file for license text and copyright information.

Third-pary open source code used are listed in our package.json file.