grunt-usemin

Replaces references from non-optimized scripts, stylesheets and other assets to their optimized version within a set of HTML files (or any templates/views).

Important

3.1.0 has a breaking change with uglify step renamed to uglify to be consistent with grunt-contrib-uglify task which name is uglify (and not uglifyjs).

Stick to 3.0.0 while we find a good solution to not have a breaking change while having name consistency.

Maintainer wanted

Notice

grunt-usemin is going under some major developments to tackle the long list of issues. As they might break with master they are merged into dev branch.

Currently what has been merged:

• Support for a resolveSource function option
• Warning for any missing files instead of silent errors
• Migrate from regex to HTML parser
• Support for multiple target (current)

Getting Started

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, install this plugin with this command:

$ npm install grunt-usemin --save-dev

Tasks

usemin replaces the references of scripts, stylesheets and other assets within HTML files dynamically with optimized versions of them. To do this usemin exports 2 built-in tasks called useminPrepare and usemin and utilizes a couple of other Grunt plugins for the optimization process. usemin does this by generating the subtasks for these Grunt plugins dynamically.

The built-in tasks of usemin:

• useminPrepare prepares the configuration to transform specific blocks in the scrutinized file into a single line, targeting an optimized version of the files. This is done by generating subtasks called generated for each of the optimization steps handled by the Grunt plugins listed below.
• usemin replaces the blocks by the file they reference, and replaces all references to assets by their revisioned version if it is found on the disk. This target modifies the files it is working on.

Grunt plugins which usemin can use to optimize files:

• concat concatenates files (usually JS or CSS).
• uglify minifies JS files.
• cssmin minifies CSS files.
• filerev revisions static assets through a file content hash.

To install these plugins, run:

$ npm install grunt-contrib-concat grunt-contrib-uglify grunt-contrib-cssmin grunt-filerev --save-dev

Important: You still need to manually install and load these dependencies.

In a typical usemin setup you launch useminPrepare first, then call every optimization step you want through their generated subtask and call usemin in the end. It could look like this:

// simple build task
grunt.registerTask('build', [
  'useminPrepare',
  'concat:generated',
  'cssmin:generated',
  'uglify:generated',
  'filerev',
  'usemin'
]);

The useminPrepare task

useminPrepare task updates the grunt configuration to apply a configured transformation flow to tagged files (i.e. blocks). By default the transformation flow is composed of concat and uglify for JS files, but it can be configured.

Blocks

Blocks are expressed as:

<!-- build:<type>(alternate search path) <path> -->
... HTML Markup, list of script / link tags.
<!-- endbuild -->

• type: can be js, css or a custom type with a block replacement function defined
• If another type, the block will be ignored. Useful for "development only" blocks that won't appear in your build
• alternate search path: (optional) By default the input files are relative to the treated file. Alternate search path allows one to change that
• path: the file path of the optimized file, the target output

An example of this in completed form can be seen below:

<!-- build:js js/app.js -->
<script src="js/app.js"></script>
<script src="js/controllers/thing-controller.js"></script>
<script src="js/models/thing-model.js"></script>
<script src="js/views/thing-view.js"></script>
<!-- endbuild -->

Transformation flow

The transformation flow is made of sequential steps: each of the steps transform the file, and useminPrepare will modify the configuration in order for the described steps to be correctly performed.

By default the flow is: concat -> uglify. Additionally to the flow, at the end, some postprocessors can be launched to further alter the configuration.

Let's have an example, using the default flow (we're just going to look at the steps), app for input dir, dist for output dir, and the following block:

<!-- build:js js/app.js -->
<script src="js/app.js"></script>
<script src="js/controllers/thing-controller.js"></script>
<script src="js/models/thing-model.js"></script>
<script src="js/views/thing-view.js"></script>
<!-- endbuild -->

The produced configuration will look like:

{
  concat: {
    generated: {
      files: [
        {
          dest: '.tmp/concat/js/app.js',
          src: [
            'app/js/app.js',
            'app/js/controllers/thing-controller.js',
            'app/js/models/thing-model.js',
            'app/js/views/thing-view.js'
          ]
        }
      ]
    }
  },
  uglify: {
    generated: {
      files: [
        {
          dest: 'dist/js/app.js',
          src: [ '.tmp/concat/js/app.js' ]
        }
      ]
    }
  }
}

Directories

Internally, the task parses your HTML markup to find each of these blocks, and initializes the corresponding Grunt config for the concat / uglify tasks when type=js, the concat / cssmin tasks when type=css.

One doesn't need to specify a concat/uglify/cssmin configuration anymore.

It uses only one target: html, with a list of the concerned files. For example, in your Gruntfile.js:

By default, it will consider the directory where the looked-at file is located as the 'root' filesystem. Each relative path (for example to a JavaScript file) will be resolved from this path. Same goes for the absolute ones. If you need to change the 'root' dir, use the root option (see below).

useminPrepare: {
  html: 'index.html'
}

Targets can also be configured using the grunt src-dest files syntax http://gruntjs.com/configuring-tasks#files, e.g.

useminPrepare: {
  foo: {
    src: ['index.html', 'another.html']
  },
  bar: {
    src: 'index.html'
  }
}

Options

dest

Type: string
Default: nil

Base directory where the transformed files should be output.

staging

Type: string
Default: .tmp

Base directory where the temporary files should be output (e.g. concatenated files).

root

Type: string, array
Default: null

The root directory from which your files will be resolved.

flow

Type: object
Default: { steps: { js: ['concat', 'uglify'], css: ['concat', 'cssmin'] }, post: {} }

This allow you to configure the workflow, either on a per-target basis, or for all the targets. You can change the steps or the post-processors (post) separately.

For example:

• to change the js steps and post for the target html:

useminPrepare: {
  html: 'index.html',
  options: {
    flow: {
      html: {
        steps: {
          js: ['uglify']
        },
        post: {}
      }
    }
  }
}

• to change the js steps and post for all targets:

useminPrepare: {
  html: 'index.html',
  options: {
    flow: {
      steps: {
        js: ['uglify']
      },
      post: {}
    }
  }
}

• to customize the generated configuration via post-processors:

useminPrepare: {
  html: 'index.html',
  options: {
    flow: {
      steps: {
        js: ['uglify']
      },
      post: {
        js: [{
          name: 'uglify',
          createConfig: function (context, block) {
            var generated = context.options.generated;
            generated.options = {
              foo: 'bar'
            };
          }
        }]
      }
    }
  }
}

The given steps or post-processors may be specified as strings (for the default steps and post-processors), or as an object (for the user-defined ones).

User-defined steps and post-processors

User-defined steps and post-processors must have 2 attributes:

• name: name of the Gruntfile attribute that holds the corresponding config
• createConfig which is a 2 arguments function ( a context and the treated block)

For an example of steps/post-processors, you can have a look at concat and uglify in the lib/config directory of this repository.

createConfig

The createConfig function is responsible for creating (or updating) the configuration associated to the current step/post-processor. It takes 2 arguments ( a context and the treated block), and returns a configuration object.

context

The context object represent the current context the step/post-processor is running in. As the step/post-processor is a step of a flow, it must be listed in the input files and directory it must write a configuration for, potentially the already existing configuration. It must also indicate to the other steps/post-processor which files it will output in which directory. All this information is held by the context object. Attributes:

• inDir: the directory where the input file for the step/post-processors will be
• inFiles: the list of input file to take care of
• outDir: where the files created by the step/post-processors will be
• outFiles: the files that are going to be created
• last: whether or not we're the last step of the flow
• options: options of the Gruntfile.js for this step (e.g. if the step is named foo, holds configuration of the Gruntfile.js associated to the attribute foo)

block

The actual looked-at block, parsed and put in a structure.

Example: The following block

<!-- build:js scripts/site.js -->',
<script src="foo.js"></script>',
<script src="bar.js"></script>',
<script src="baz.js"></script>',
<!-- endbuild -->'

is parsed as, and given to createConfig as:

var block = {
  type: 'js',
  dest: 'scripts/site.js',
  src: [
    'foo.js',
    'bar.js',
    'baz.js'
  ],
  raw: [
    '    <!-- build:js scripts/site.js -->',
    '    <script src="foo.js"></script>',
    '    <script src="bar.js"></script>',
    '    <script src="baz.js"></script>',
    '    <!-- endbuild -->'
  ]
};

The usemin task

The usemin task has 2 actions:

• First it replaces all the blocks with a single "summary" line, pointing to a file creating by the transformation flow.
• Then it looks for references to assets (i.e. images, scripts, ...), and tries to replace them with their revved version if it can find one on disk

Finding assets

By default usemin will look for a map object created by grunt-filerev, located in grunt.filerev.summary. If it does not find it it will revert to disk lookup which is longer.

Note that by using the options.revmap (see below), you can furnish a map object.

On directories

When `usemi