Quick setup of the grunt-static-versioning plugin

grunt-static-versioning-usage.md

Repo: https://github.com/canvaspop/grunt-static-versioning

Overview

The grunt static versioning plugin generates MD5 hashes from file content and appends it to the filename. This allows for better versioning as the hash only changes when the file content changes.

The plugin leverages the grunt-contrib-uglify and grunt-contrib-cssmin tasks to handle the CSS/JS concat/minification.

Getting Started

This plugin requires Grunt ~0.4.0

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.

Setup task

1. Install the dependencies.

npm install grunt-static-versioning --save-dev
npm install grunt-contrib-cssmin --save-dev
npm install grunt-contrib-uglify --save-dev

2. Load tasks

In your Gruntfile.js load the previously installed tasks.

grunt.loadNpmTasks( 'grunt-static-versioning' );
grunt.loadNpmTasks( 'grunt-contrib-cssmin' );
grunt.loadNpmTasks( 'grunt-contrib-uglify' );

3. Setup tasks

This won't cover setting up the uglify and cssmin, for more information see the official repos at: https://github.com/gruntjs/grunt-contrib-uglify and https://github.com/gruntjs/grunt-contrib-cssmin.

Note: Using a tmp directory for the cssmin and uglify targets allows the grunt-static-versioning plugin to alter files before moving them to the final output directory.

cssmin and uglify:

cssmin: {
    main: {
        files: [{
            src: [ 'main.css' ],
            dest: 'tmp/main.min.css'
        }]
    }
},

uglify: {
    main: {
        files: [{
            src: [
                'file.one.js',
                'file.two.js'
            ],
            dest: 'tmp/main.min.js'
        }]
    },
    
    plugin: {
        files: [{
            src: [
                'file.three.js',
                'file.four.js'
            ],
            dest: 'tmp/plugin.min.js'
        }]
    }
}

versioning:

versioning: {
    options: {
        cwd: 'public',
        outputConfigDir: 'public/config'
    },
    dev: {
        options: {
            env: 'dev'
        },
        files: [{
            assets: '<%= uglify.main.files %>',
            key: 'global',
            dest: 'js',
            type: 'js',
            ext: '.min.js'
        }, {
            assets: '<%= uglify.plugin.files %>',
            key: 'global',
            dest: 'js',
            type: 'js',
            ext: '.min.js'
        }, {
            assets: '<%= cssmin.main.files %>',
            key: 'global',
            dest: 'css',
            type: 'css',
            ext: '.min.css'
        }]
    },
    prod: {
        files: [{
            assets: '<%= uglify.main.files %>',
            key: 'global',
            dest: 'js',
            type: 'js',
            ext: '.min.js'
        }, {
            assets: '<%= uglify.plugin.files %>',
            key: 'global',
            dest: 'js',
            type: 'js',
            ext: '.min.js'
        }, {
            assets: '<%= cssmin.main.files %>',
            key: 'global',
            dest: 'css',
            type: 'css',
            ext: '.min.css'
        }]
    }
}

4. Register tasks

grunt.registerTask( 'build:dev', [ 'versioning:dev' ] );
grunt.registerTask( 'build:prod', [ 'uglify', 'cssmin', 'versioning:prod' ] );

5. Run grunt

grunt build:dev
// or 
grunt build:prod

6. Output

After running grunt build:prod or grunt build:dev, a config file will be generated at the outputConfigDir location. In this case public/config/assets.config.json

Dev output

grunt build:dev

{
  "staticAssets": {
    "global": {
      "js": [
        "/file.one.js",
        "/file.two.js",
        "/file.three.js",
        "/file.four.js"
      ],
      "css": [
        "/main.css"
      ]
    }
  }
}

Prod output

grunt build:prod

{
  "staticAssets": {
    "global": {
      "js": [
        "/main.cce1a4ed.min.js",
        "/plugin.71f3b3f2.min.js"
      ],
      "css": [
        "/main.b6f17edb.min.css"
      ]
    }
  }
}

7. Using the config file

The generated config file will contain either the source files or the generated versioned files. Currently it can be outputted in JSON or PHP. There will be adapter examples for various languages in the repo, e.g. see nodejs+express example

===

For full usage and options available see the repo description.