grunt-cssuglifier

This plugin minifies the CSS class names in a given CSS file. Additionally a JSON mapping file and a JS mapping file can be created automatically for usage within other grunt tasks or other parts of your application.

By default this plugin preserves class name suffixes so it can be used for easier handling BEM style modifiers.

Example input:

.block {
    display: block;
}

.block--inactive {
    display: none
}

.block__element {
    display: none;
    border: 1px solid #000;
}

.block__element--active {
    border: 1px solid #f00;
}

Example output:

.b5 {
    display: block;
}

.b5--inactive {
    display: none
}

.c28 {
    display: none;
    border: 1px solid #000;
}

.c28--active {
    border: 1px solid #f00;
}

Getting Started

This plugin requires Grunt ~0.4.5

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-cssuglifier --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-cssuglifier');

The "cssuglifier" task

Overview

In your project's Gruntfile, add a section named cssuglifier to the data object passed into grunt.initConfig().

grunt.initConfig({
  cssuglifier: {
    options: {
      classPrefix: '\\.',
      keepBemModifier: 1,
      bemModifierPrefix: '--',
      
      createJsonMapFile: true,
      jsonMapFilePath: this.name + '_mapping.json',
      
      createJSMapFile: 1,
      jsMapVarDefinition: 'var ' + this.name + 'Map',
      jsMapFilePath: this.name + '_mapping.js',
      
      prependMapJson: '',
      appendMapJson: '',
      
      fileNameSuffix: '.ugly'
    },
    files: {
      src: 'src/**/*',
      dest: 'result'
    }
  },
});

Options

files.src

Type: String|Array

The path to the source files for uglification. You can define an array of files

...
  files: {
    src: ['src/a.css', 'src/b.css', 'src/c.css'],
    ...
  }
...

or you can define as single file

...
  files: {
    src: 'src/foo.css',
    ...
  }
...

or you can use globbing as well

...
  files: {
    src: 'src/**/*.css',
    ...
  }
...

Your can also add JS files here, but please note that those files are only used for the map file generation. So the classes found within JS files will not be merged into the CSS file.

files.dest

Type: String

The target for saving the uglified CSS files. Subdirectories from the source folder will be preserved. If this value and the value of options.fileNameSuffix are empty, the source files will be overwritten.

options.keepBemModifier

Type: Bool Default value: true

This is for BEM class name usage but actually you can define any kind of suffix that will be preserved if found at the end of a class name.

options.classPrefix

Type: String Default value: '\\.'

If you prefer to use the script for something else than classes (for example IDs) this is what you have to change. Please note the double backslash in front of the dot in the default value. As this string will be passed to RegExp, it has to be escaped.

An example usage to replace class names & IDs:

...
options: {
  ...
  'classPrefix': '[\\.#]+'
  ...
}
...

options.fileNameSuffix

Type: String Default value: '.ugly'

This suffix will be prepended to the actual file ending of you CSS files. So styles.css would result in styles.ugly.css by default. If this value and the value of files.dest are empty, the source files will be overwritten.

options.bemModifierPrefix

Type: String Default value: '--'

Separator between the BEM modifier as described above and the actual class name.

options.createJsonMapFile

Type: Bool Default value: true

This will create a JSON file that contains an object with the mapping of the transformed class names. The format is:

{
  ...
  'actualLongClassName': 'ugly',
  'anpotherLongClassName': 'uygl'
  ...
}

options.jsonMapFilePath

Type: String Default value: 'cssuglifier_mapping.json'

The path to the JSON file described above.

options.createJSMapFile

Type: Boold Default value: true

Creates a '.js' file similar to the JSON file but the JSON object is wrapped by a variable assignment. This way the result file can be combined into an uglifyJS task or something similar.

options.jsMapFilePath

Type: String Default value: 'cssuglifier_mapping.js'

The path to the JS-file described above.

options.jsMapVarDefinition

Type: String Default value: 'var cssuglifierMap'

The result by default is:

var cssuglifierMap = {'actualLongClassName': 'ugly'};

You can also change this to an object property assignment. For example a change to 'myApp.cssMapping' would result in:

myApp.cssMapping = {'actualLongClassName': 'ugly'};

options.prependMapJson

Type: String Default value: ''

Path to a JSON file that will be merged with the automatically created map files. So you can append class names that are not defined in the CSS source file(s). Please note that the the auto-generated JSON map overwrites existing values within this map file.

options.appendMapJson

Type: String Default value: ''

Similar to options.prependMapJson but overwrites existing values of the auto-generated JSON map.

Usage Examples

grunt.initConfig({
  cssuglifier: {
    options: {},
    files: {
      src: 'src/**/*',
      dest: 'dest'
    }
  },
});