Home

Awesome

Build Status

Deprecated. Please use Browserify or Webpack

gulp-usemin

Replaces references to non-optimized scripts or stylesheets into a set of HTML files (or any templates/views).

This task is designed for gulp >= 3 and node >= 4.0.

Attention: v0.3.0 options is not compatible with v0.2.0.

Usage

First, install gulp-usemin as a development dependency:

npm install --save-dev gulp-usemin

Then, add it to your gulpfile.js:

var usemin = require('gulp-usemin');
var uglify = require('gulp-uglify');
var htmlmin = require('gulp-htmlmin');
var cleanCss = require('gulp-clean-css');
var rev = require('gulp-rev');


gulp.task('usemin', function() {
  return gulp.src('./*.html')
    .pipe(usemin({
      css: [ rev() ],
      html: [ htmlmin({ collapseWhitespace: true }) ],
      js: [ uglify(), rev() ],
      inlinejs: [ uglify() ],
      inlinecss: [ cleanCss(), 'concat' ]
    }))
    .pipe(gulp.dest('build/'));
});

If you need to call the same pipeline twice, you need to define each task as a function that returns the stream object that should be used.

gulp.task('usemin', function() {
  return gulp.src('./*.html')
    .pipe(usemin({
      css: [ rev ],
      html: [ function () {return htmlmin({ collapseWhitespace: true });} ],
      js: [ uglify, rev ],
      inlinejs: [ uglify ],
      inlinecss: [ cleanCss, 'concat' ]
    }))
    .pipe(gulp.dest('build/'));
});

API

Blocks

Blocks are expressed as:

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

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

<!-- build:css style.css -->
<link rel="stylesheet" href="css/clear.css"/>
<link rel="stylesheet" href="css/main.css"/>
<!-- endbuild -->

<!-- build:htmlimport components-packed.html -->
<link rel="import" href="components-a.html">
<link rel="import" href="components-b.html">
<!-- endbuild -->

<!-- build:js js/lib.js -->
<script src="../lib/angular-min.js"></script>
<script src="../lib/angular-animate-min.js"></script>
<!-- endbuild -->

<!-- build:js1 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 -->

<!-- build:remove -->
<script src="js/localhostDependencies.js"></script>
<!-- endbuild -->

<!-- build:inlinejs -->
<script src="../lib/angular-min.js"></script>
<script src="../lib/angular-animate-min.js"></script>
<!-- endbuild -->

<!-- build:inlinecss -->
<link rel="stylesheet" href="css/clear.css"/>
<link rel="stylesheet" href="css/main.css"/>
<!-- endbuild -->

Options

assetsDir

Type: String

Alternate root path for assets. New concated js and css files will be written to the path specified in the build block, relative to this path. Currently asset files are also returned in the stream.

path

Type: String

Default alternate search path for files. Can be overridden by the alternate search path option for a given block.

any pipelineId

Type: Array

If exist used for modify files. If does not contain string 'concat', then it added as first member of pipeline

outputRelativePath

Type: String Relative location to html file for new concatenated js and css.

enableHtmlComment

Type: Boolean

Keep HTML comment when processing

jsAttributes

Type: Object

Attach HTML attributes to the output js file. For Example :

gulp.task('usemin', function() {
  return gulp.src('./index.html')
    .pipe(usemin({
      html: [],
      jsAttributes : {
        async : true,
        lorem : 'ipsum',
        seq   : [1, 2, 1]
      },
      js: [ ],
      js1:[ ],
      js2:[ ]
    }))
    .pipe(gulp.dest('./'));
});

Will give you :

<script src="./lib.js" async lorem="ipsum" seq="1"></script>
<script src="./app.js" async lorem="ipsum" seq="2"></script>
<script src="./extra.js" async lorem="ipsum" seq="1"></script>

As your built script tag.

skipMissingResources

Type: Boolean

Allows missing resources to be skipped, instead of throwing an error.

Use case

|
+- app
|   +- index.html
|   +- assets
|       +- js
|          +- foo.js
|          +- bar.js
|   +- css
|       +- clear.css
|       +- main.css
+- dist

We want to optimize foo.js and bar.js into optimized.js, referenced using relative path. index.html should contain the following block:

    <!-- build:css style.css -->
    <link rel="stylesheet" href="css/clear.css"/>
    <link rel="stylesheet" href="css/main.css"/>
    <!-- endbuild -->

    <!-- build:js js/optimized.js -->
    <script src="assets/js/foo.js"></script>
    <script src="assets/js/bar.js"></script>
    <!-- endbuild -->

We want our files to be generated in the dist directory. gulpfile.js should contain the following block:

gulp.task('usemin', function () {
  return gulp.src('./app/index.html')
      .pipe(usemin({
        js: [uglify()]
        // in this case css will be only concatenated (like css: ['concat']).
      }))
      .pipe(gulp.dest('dist/'));
});

This will generate the following output:

|
+- app
|   +- index.html
|   +- assets
|       +- js
|          +- foo.js
|          +- bar.js
+- dist
|   +- index.html
|   +- js
|       +- optimized.js
|   +- style.css

index.html output:

    <link rel="stylesheet" href="style.css"/>

    <script src="js/optimized.js"></script>

Changelog

#####0.3.30

#####0.3.29

#####0.3.28

#####0.3.27

#####0.3.26

#####0.3.24

#####0.3.23

#####0.3.22

#####0.3.21

#####0.3.20

#####0.3.18

#####0.3.17

#####0.3.16

#####0.3.15

#####0.3.14

#####0.3.13

#####0.3.12

#####0.3.11

#####0.3.10

#####0.3.9

#####0.3.8

#####0.3.7

#####0.3.6

#####0.3.5

#####0.3.4

#####0.3.3

#####0.3.2

#####0.3.1

#####0.3.0

#####0.2.3

#####0.2.2

#####0.2.1

#####0.2.0

#####0.1.4

#####0.1.3

#####0.1.1

#####0.1.0

#####0.0.2

#####0.0.1