gulp-useref
Parse build blocks in HTML files to replace references to non-optimized scripts or stylesheets with useref
Inspired by the grunt plugin grunt-useref. It can handle file concatenation but not minification. Files are then passed down the stream. For minification of assets or other modifications, use gulp-filter to filter specific types of assets.
Install with npm
npm install --save-dev gulp-useref
The following example will parse the build blocks in the HTML, replace them and pass those files through. Assets inside the build blocks will be concatenated and passed through in a stream as well.
var gulp = require('gulp'),
useref = require('gulp-useref');
gulp.task('default', function () {
return gulp.src('app/*.html')
.pipe(useref.assets())
.pipe(useref.restore())
.pipe(useref())
.pipe(gulp.dest('dist'));
});
If you want to minify your assets or perform some other modification, you can use gulp-filter to handle specific types of assets. When you want all the original files back, just call the restore method.
var gulp = require('gulp'),
useref = require('gulp-useref'),
filter = require('gulp-filter'),
uglify = require('gulp-uglify'),
minifyCss = require('gulp-minify-css');
gulp.task('html', function () {
var jsFilter = filter('**/*.js');
var cssFilter = filter('**/*.css');
return gulp.src('app/*.html')
.pipe(useref.assets())
.pipe(jsFilter)
.pipe(uglify())
.pipe(jsFilter.restore())
.pipe(cssFilter)
.pipe(minifyCss())
.pipe(cssFilter.restore())
.pipe(useref.restore())
.pipe(useref())
.pipe(gulp.dest('dist'));
});
Blocks are expressed as:
<!-- build:<type>(alternate search path) <path> -->
... HTML Markup, list of script / link tags.
<!-- endbuild -->
- type: either
js
orcss
- 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:
<html>
<head>
<!-- build:css css/combined.css -->
<link href="css/one.css" rel="stylesheet">
<link href="css/two.css" rel="stylesheet">
<!-- endbuild -->
</head>
<body>
<!-- build:js scripts/combined.js -->
<script type="text/javascript" src="scripts/one.js"></script>
<script type="text/javascript" src="scripts/two.js"></script>
<!-- endbuild -->
</body>
</html>
The resulting HTML would be:
<html>
<head>
<link rel="stylesheet" href="css/combined.css"/>
</head>
<body>
<script src="scripts/combined.js"></script>
</body>
</html>
Returns a stream with the concatenated asset files from the build blocks inside the HTML. Available options:
searchPath
- Specify the location to search for javascript/css files, relative to the current working directory. Can be a string or array of strings.
Brings back the previously filtered out HTML files.
- ClosureCompiler.js doesn't support Buffers, which means if you want to use gulp-closure-compiler you'll have to first write out the
combined.js
to disk. See this for more information.
- Whitney Young (@wbyoung) for suggesting a separate stream for assets and the use of gulp-filter to filter assets.
MIT © Jonathan Kemp