{
"name": "grunt-usemin",
"version": "2.6.0",
"license": "BSD-2-Clause",
"author": {
"name": "The Yeoman Team"
},
"description": "Replaces references to non-optimized scripts or stylesheets into a set of HTML files (or any templates/views).",
"keywords": [
"gruntplugin",
"usemin",
"yeoman",
"html",
"css",
"optimize"
],
"homepage": "https://github.com/yeoman/grunt-usemin",
"repository": {
"type": "git",
"url": "https://github.com/yeoman/grunt-usemin.git"
},
"bugs": {
"url": "https://github.com/yeoman/grunt-usemin/issues"
},
"scripts": {
"test": "grunt test"
},
"dependencies": {
"chalk": "~0.5.1",
"debug": "~2.1.0",
"lodash": "~2.4.1"
},
"devDependencies": {
"grunt": "~0.4.5",
"grunt-contrib-jshint": "~0.10.0",
"grunt-jscs": "~0.8.0",
"grunt-mocha-cli": "~1.10.0",
"mkdirp": "~0.5.0",
"rimraf": "~2.2.8"
},
"peerDependencies": {
"grunt": ">=0.4.0"
},
"engines": {
"node": ">=0.10.0"
},
"files": [
"lib",
"tasks"
],
"readme": "# grunt-usemin [![Build Status](https://secure.travis-ci.org/yeoman/grunt-usemin.svg?branch=master)](http://travis-ci.org/yeoman/grunt-usemin)\n\n> Replaces references from non-optimized scripts, stylesheets and other assets to their optimized version within a set of HTML files (or any templates/views).\n\n**[Maintainer wanted](https://github.com/yeoman/grunt-usemin/issues/313)**\n\n\n## Getting Started\nIf you haven't used [grunt][] before, be sure to check out the [Getting Started][] guide, as it explains how to create a [gruntfile][Getting Started] as well as install and use grunt plugins. Once you're familiar with that process, install this plugin with this command:\n\n```shell\nnpm install grunt-usemin --save-dev\n```\n\n[grunt]: http://gruntjs.com/\n[Getting Started]: http://gruntjs.com/getting-started\n\n## Tasks\n\n`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.\n\nThe built-in tasks of `usemin`:\n* `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 every optimization steps handled by the Grunt plugins listed below.\n* `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.\n\nGrunt plugins which `usemin` can use to optimize files:\n* [`concat`](https://github.com/gruntjs/grunt-contrib-concat) concatenates files (usually JS or CSS).\n* [`uglify`](https://github.com/gruntjs/grunt-contrib-uglify) minifies JS files.\n* [`cssmin`](https://github.com/gruntjs/grunt-contrib-cssmin) minifies CSS files.\n* [`filerev`](https://github.com/yeoman/grunt-filerev) revisions static assets through a file content hash.\n\nTo install required plugins, run:\n```\nnpm install grunt-contrib-concat grunt-contrib-uglify grunt-contrib-cssmin grunt-filerev --save\n```\n\n**Important**: _You still need to manually install and load these dependencies_.\n\nIn 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:\n\n```js\n// simple build task\ngrunt.registerTask('build', [\n 'useminPrepare',\n 'concat:generated',\n 'cssmin:generated',\n 'uglify:generated',\n 'filerev',\n 'usemin'\n]);\n```\n\n## The useminPrepare task\n\n`useminPrepare` task updates the grunt configuration to apply a configured transformation flow to tagged files (i.e. blocks).\nBy default the transformation flow is composed of `concat` and `uglifyjs` for JS files, but it can be configured.\n\n### Blocks\nBlocks are expressed as:\n\n```html\n\n... HTML Markup, list of script / link tags.\n\n```\n\n* **type**: can be `js`, `css` or a custom type with a [block replacement function](#blockreplacements) defined\n * If another type, the block will be ignored. Useful for \"development only\" blocks that won't appear in your build\n* **alternate search path**: (optional) By default the input files are relative to the treated file. Alternate search path allows one to change that\n* **path**: the file path of the optimized file, the target output\n\nAn example of this in completed form can be seen below:\n\n```html\n\n\n\n\n\n\n```\n\n### Transformation flow\n\nThe 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.\n\nBy default the flow is: `concat -> uglifyjs`.\nAdditionally to the flow, at the end, some postprocessors can be launched to further alter the configuration.\n\nLet'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:\n\n```html\n\n\n\n\n\n\n```\nThe produced configuration will look like:\n\n```js\n{\n concat: {\n generated: {\n files: [\n {\n dest: '.tmp/concat/js/app.js',\n src: [\n 'app/js/app.js',\n 'app/js/controllers/thing-controller.js',\n 'app/js/models/thing-model.js',\n 'app/js/views/thing-view.js'\n ]\n }\n ]\n }\n },\n uglify: {\n generated: {\n files: [\n {\n dest: 'dist/js/app.js',\n src: [ '.tmp/concat/js/app.js' ]\n }\n ]\n }\n }\n}\n```\n\n### Directories\n\nInternally, 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`.\n\nOne doesn't need to specify a concat/uglify/cssmin configuration anymore.\n\nIt uses only one target: `html`, with a list of the concerned files. For example, in your `Gruntfile.js`:\n\nBy 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.\nIf you need to change the 'root' dir, use the `root` option (see below).\n\n```js\nuseminPrepare: {\n html: 'index.html'\n}\n```\n\nTargets can also be configured using the grunt src-dest files syntax http://gruntjs.com/configuring-tasks#files, e.g.\n\n```js\nuseminPrepare: {\n foo: {\n src: ['index.html', 'another.html']\n },\n bar: {\n src: 'index.html'\n }\n}\n```\n\n### Options\n\n### dest\n\nType: 'string' \nDefault: `nil`\n\nBase directory where the transformed files should be output.\n\n### staging\n\nType: 'string' \nDefault: `.tmp`\n\nBase directory where the temporary files should be output (e.g. concatenated files).\n\n### root\n\nType: 'string' or 'Array' \nDefault: `nil`\n\nThe root directory from which your files will be resolved.\n\n### flow\n\nType: 'object' \nDefault: `{ steps: { js: ['concat', 'uglifyjs'], css: ['concat', 'cssmin'] }, post: {} }`\n\nThis allow you to configure the workflow, either on a per-target basis, or for all the targets.\nYou can change the `steps` or the post-processors (`post`) separately.\n\nFor example:\n\n* to change the `js` `steps` and `post` for the target `html`:\n\n```js\nuseminPrepare: {\n html: 'index.html',\n options: {\n flow: {\n html: {\n steps: {\n js: ['uglifyjs']\n },\n post: {}\n }\n }\n }\n}\n```\n\n* to change the `js` `steps` and `post` for all targets:\n\n```js\nuseminPrepare: {\n html: 'index.html',\n options: {\n flow: {\n steps: {\n js: ['uglifyjs']\n },\n post: {}\n }\n }\n}\n```\n\n* to customize the generated configuration via post-processors:\n\n```js\nuseminPrepare: {\n html: 'index.html',\n options: {\n flow: {\n steps: {\n js: ['uglifyjs']\n },\n post: {\n js: [{\n name: 'uglify',\n createConfig: function (context, block) {\n var generated = context.options.generated;\n generated.options = {\n foo: 'bar'\n };\n }\n }]\n }\n }\n }\n}\n```\n\nThe 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).\n\n#### User-defined steps and post-processors\n\nUser-defined steps and post-processors must have 2 attributes:\n\n* `name`: name of the `Gruntfile` attribute that holds the corresponding config\n* `createConfig` which is a 2 arguments function ( a `context` and the treated `block`)\n\nFor an example of steps/post-processors, you can have a look at `concat` and `uglifyjs` in the `lib/config` directory of this repository.\n\n##### `createConfig`\n\nThe `createConfig` function is responsible for creating (or updating) the configuration associated to the current step/post-processor.\nIt takes 2 arguments ( a `context` and the treated `block`), and returns a configuration object.\n\n###### `context`\nThe `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.\nAttributes:\n\n* `inDir`: the directory where the `input` file for the step/post-processors will be\n* `inFiles`: the list of input file to take care of\n* `outDir`: where the files created by the step/post-processors will be\n* `outFiles`: the files that are going to be created\n* `last`: whether or not we're the last step of the flow\n* `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`)\n\n###### `block`\nThe actual looked-at block, parsed an put in a structure.\n\nExample:\nThe following block\n```html\n',\n',\n',\n',\n'\n```\n\nis parsed as, and given to `createConfig` as:\n\n```js\nvar block = {\n type: 'js',\n dest: 'scripts/site.js',\n src: [\n 'foo.js',\n 'bar.js',\n 'baz.js'\n ],\n raw: [\n ' ',\n ' ',\n ' ',\n ' ',\n ' '\n ]\n};\n```\n\n## The usemin task\n\nThe `usemin` task has 2 actions:\n\n* First it replaces all the blocks with a single \"summary\" line, pointing to a file creating by the transformation flow.\n* 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\n\n### Finding assets\n\nBy default `usemin` will look for a map object created by [grunt-filerev](https://github.com/yeoman/grunt-filerev), located in `grunt.filerev.summary`. If it does not find it it will revert to disk lookup which is longer.\n\nNote that by using the `options.revmap` (see below), you can furnish a map object.\n\n### On directories\n\nWhen `usemin` tries to replace referenced assets with their revved version it has to look at a collection of directories (asset search paths): for each of the directories of this collection it will look at the below tree, and try to find the revved version.\nThis asset search directories collection is by default set to the location of the file that is scrutinized but can be modified (see Options below).\n\n#### Example 1: file `dist/html/index.html` has the following content:\n\n```html\n\n\n```\nBy default `usemin` will look under `dist/html` for revved versions of:\n\n* `styles/main.css`: a revved version of `main.css` will be looked at under the `dist/html/styles` directory. For example a file `dist/html/styles/main.1234.css` will match (although `dist/html/main.1234.css` won't: the path of the referenced file is important)\n* `../images/test.png`: it basically means that a revved version of `test.png` will be looked for under the `dist/images` directory\n\n#### Example 2: file `dist/html/index.html` has the following content:\n\n```html\n\n\n```\nBy default `usemin` will look under `dist/html` for revved versions of `styles/main.css` and `images/test.png`. Now let's suppose our assets are scattered in `dist/assets`. By changing the asset search path list to `['dist/assets']`, the revved versions of the files will be searched for under `dist/assets` (and thus, for example, `dist/assets/images/test.875487.png` and `dist/assets/styles/main.98090.css`) will be found.\n\n### Options\n\n#### assetsDirs\n\nType: 'Array' \nDefault: Single item array set to the value of the directory where the currently looked at file is.\n\nList of directories where we should start to look for revved version of the assets referenced in the currently looked at file.\n\nExample:\n```js\nusemin: {\n html: 'build/index.html',\n options: {\n assetsDirs: ['foo/bar', 'bar']\n }\n}\n```\n\n#### patterns\n\nType: 'Object' \nDefault: Empty\n\nAllows for user defined pattern to replace reference to files. For example, let's suppose that you want to replace\nall references to `'image.png'` in your Javascript files by the revved version of `image.png` found below the directory `images`.\nBy specifying something along the lines of:\n\n```js\nusemin: {\n js: '*.js',\n options: {\n assetsDirs: 'images',\n patterns: {\n js: [\n [/(image\\.png)/, 'Replacing reference to image.png']\n ]\n }\n }\n}\n```\n\nSo in short:\n\n* key in pattern should match the target (e.g `js` key for the target `js`)\n* Each pattern is an array of arrays. These arrays are composed of 4 items (last 2 are optional):\n * First one if the regexp to use. The first group is the one that is supposed to represent the file\n reference to replace\n * Second one is a logging string\n * FIXME\n * FIXME\n\n#### blockReplacements\n\nType: 'Object' \nDefault: `{ css: function (block) { ... }, js: function (block) { ... } }`\n\nThis lets you define how blocks get their content replaced. Useful to have block types other that `css` and `js`.\n\n* Object key matches a block type\n* Value is the replacement function for that block type.\n * The replacement function gets called with a single argument: a [block](#block) object.\n * Must return a `String`, the \"summary\" line that will replace the block content.\n\nFor example, to create a `less` block you could define its replacement function like this:\n\n```js\nusemin: {\n html: 'index.html',\n options: {\n blockReplacements: {\n less: function (block) {\n return '';\n }\n }\n }\n}\n```\n\n#### revmap\n\nType: 'String' \nDefault: Empty\n\nIndicate the location of a map file, as produced by `grunt-filerev` for example. This map file is a simple JSON file, holding an object\nwhich attributes are the original file and associated value is the transformed file. For example:\n\n```js\n{\n \"foo.png\": \"foo.1234.png\"\n}\n```\nThis map will be used instead of looking for file on the disk.\n\n## On directories\nThe main difference to be kept in mind, regarding directories and tasks, is that for `useminPrepare`, the directories needs to indicate the input,\ntransient and output path needed to output the right configuration for the processors pipeline,\nwhereas in the case of `usemin` it only reflects the output paths, as all the needed assets should have\nbeen output to the destination dir (either transformed or just copied)\n\n### useminPrepare\n`useminPrepare` is trying to prepare the right configuration for the pipeline of actions that are going to be\napplied on the blocks (for example concatenation and uglify-cation). As such it needs to have the input\ndirectory, temporary directories (staging) and destination directory.\nThe files referenced in the block are either absolute or relative (`/images/foo.png` or `../../images/foo.png`).\nAbsolute files references are looked in a given set of search path (input), which by default is set\nto the directory where the html/css file examined is located (can be overridden per block, or more\ngenerally through `root` option).\nRelative files references are also looked at from location of the examined file, unless stated otherwise.\n\n\n### usemin\n`usemin` target replaces references to images, scripts, css, ... in the furnished files (html, css, ...).\nThese references may be either absolute (i.e. `/images/foo.png`) or relative (i.e. `image/foo.png`\nor `../images/foo.png`).\nWhen the reference is absolute a set of asset search paths should be looked at under the\ndestination directory (for example, using the previous example, and `searchpath`\nequal to `['assets']`, `usemin` would try to find either a revved version of the image\nof the image below the `assets` directory: for example `dest/assets/images/foo.1223443.png`).\nWhen the reference is relative, by default the referenced item is looked in the path\nrelative *to the current file location* in the destination directory (e.g. with the\npreceding example, if the file is `build/bar/index.html`, then transformed `index.html`\nwill be in `dist/bar`, and `usemin` will look for `dist/bar/../images/foo.32323.png`).\n\n\n## Use cases\n\n### Simple one\n\n```\n|\n+- app\n| +- index.html\n| +- assets\n| +- js\n| +- foo.js\n| +- bar.js\n+- dist\n\n```\n\nWe want to optimize `foo.js` and `bar.js` into `optimized.js`, referenced using relative path. `index.html` should contain the following block:\n\n```html\n\n\n\n\n```\n\nWe want our files to be generated in the `dist` directory.\n\nBy using the following `useminPrepare` config:\n\n```js\n{\n useminPrepare: {\n html: 'app/index.html',\n options: {\n dest: 'dist'\n }\n }\n}\n```\n\nThis will, on the fly, generate the following configuration:\n\n```js\n{\n concat:\n {\n '.tmp/concat/assets/js/optimized.js': [\n 'app/assets/js/foo.js',\n 'app/assets/js/bar.js'\n ]\n },\n\n uglify:\n {\n 'dist/assets/js/optimized.js': ['.tmp/concat/assets/js/optimized.js']\n }\n}\n```\n\n### HTML file and asset files in sibling directories\n```\napp\n|\n+- html\n| +- index.html\n+- assets\n| +- js\n| +- foo.js\n| +- bar.js\n+- dist\n\n```\n\nWe want to optimize `foo.js` and `bar.js` into `optimized.js`, referenced using absolute path. `index.html` should contain the following block:\n\n```html\n\n\n\n\n```\n\nWe want our files to be generated in the `dist` directory.\n\nBy using the following `useminPrepare` config:\n\n```js\n{\n useminPrepare: {\n html: 'html/index.html',\n options: {\n root: 'app',\n dest: 'dist'\n }\n }\n}\n```\n\nThis will, on the fly, generate the following configuration:\n\n```js\n{\n concat:\n {\n '.tmp/concat/assets/js/optimized.js': [\n 'app/assets/js/foo.js',\n 'app/assets/js/bar.js'\n ]\n },\n\n uglify:\n {\n 'dist/assets/js/optimized.js': ['.tmp/concat/assets/js/optimized.js']\n }\n}\n```\n\n## License\n\n[BSD license](http://opensource.org/licenses/bsd-license.php) and copyright Google\n",
"readmeFilename": "README.md",
"_id": "grunt-usemin@2.6.0",
"_from": "grunt-usemin@^2.1.1"
}